# Publications

> Manage publications — the configuration that makes an agent embeddable on external sites.

**URL:** https://inference.sh/docs/api/rest/publications
**Last updated:** 2026-09-24

---

Manage **publications** — the configuration that makes an agent embeddable on external sites.

The **Publish** tab in the web app uses these endpoints. After publishing, visitors can chat via the hosted iframe or the [Embed API](/docs/api/rest/embed) without API keys. Your workspace pays for inference.

→ [Publishing and embedding agents](/docs/agents/publishing): web app workflow, origins, themes, and iframe snippets

---

## Authentication

| Scope | Access |
|-------|--------|
| `agents:read` | List and get publications |
| `agents:write` | Create, update, and delete publications |

Create keys in [settings → workspace → api keys](https://app.inference.sh/settings/team/keys). You must have **write** permission on the agent being published. The API enforces ownership in the service layer.

---

## Publication object

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Publication ID |
| `resource_type` | string | Resource kind (`agent` is the only supported value today) |
| `resource_id` | string | Agent ID |
| `namespace` | string | Agent namespace (set from the agent on create) |
| `name` | string | Agent name (set from the agent on create) |
| `allowed_origins` | string[] | Origins allowed to embed or call the embed API. Empty = all origins. |
| `rate_limit_rpm` | number | Optional per-publication rate limit (requests per minute) |
| `theme` | object | Optional `light` / `dark` color tokens for the embed UI |
| `label` | string | Optional display label |
| `enabled` | boolean | Whether the publication is active |

**Theme colors** (`theme.light`, optional `theme.dark`):

| Field | Description |
|-------|-------------|
| `primary` | Primary accent color |
| `secondary` | Secondary accent color |
| `background` | Chat background |
| `text` | Body text color |
| `border` | Border color (optional) |

---

## List publications for a resource

`GET /publications?resource_type=agent&resource_id={agentId}`

Returns all publications for the given resource (including disabled). Requires **`agents:read`**.

Both query parameters are required.

```bash
curl "https://api.inference.sh/publications?resource_type=agent&resource_id=agent_abc123" \
  -H "Authorization: Bearer inf_your_key"
```

---

## Get publication

`GET /publications/{id}`

Returns a single publication by ID. Requires **`agents:read`**.

```bash
curl https://api.inference.sh/publications/pub_abc123 \
  -H "Authorization: Bearer inf_your_key"
```

---

## Create publication

`POST /publications`

Publishes an agent. Requires **`agents:write`** and write access to the agent.

### Request

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `resource_type` | string | Yes | `agent` |
| `resource_id` | string | Yes | Agent ID to publish |
| `allowed_origins` | string[] | No | Origin allowlist (default: allow all) |
| `theme` | object | No | Embed UI branding colors |
| `label` | string | No | Optional label |
| `rate_limit_rpm` | number | No | Optional rate limit |

`namespace` and `name` are populated from the agent. New publications are created with `enabled: true`.

```bash
curl -X POST https://api.inference.sh/publications \
  -H "Authorization: Bearer inf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "agent",
    "resource_id": "agent_abc123",
    "allowed_origins": ["https://example.com"]
  }'
```

### Errors

| HTTP | When |
|------|------|
| **400** | Invalid body, agent not found, or insufficient permission on the agent |
| **403** | API key lacks `agents:write` scope |

---

## Update publication

`PUT /publications/{id}`

Update origins, theme, label, rate limit, or other fields. Requires **`agents:write`**.

Send the fields you want to persist (the web app sends the full publication object).

```bash
curl -X PUT https://api.inference.sh/publications/pub_abc123 \
  -H "Authorization: Bearer inf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_origins": ["https://example.com", "https://app.example.com"],
    "theme": {
      "light": {
        "primary": "#000000",
        "secondary": "#666666",
        "background": "#ffffff",
        "text": "#000000"
      }
    }
  }'
```

---

## Delete publication

`DELETE /publications/{id}`

Unpublish an agent (removes the publication record). Requires **`agents:write`**.

```bash
curl -X DELETE https://api.inference.sh/publications/pub_abc123 \
  -H "Authorization: Bearer inf_your_key"
```

### Response

```json
{ "deleted": true }
```

---

## After publishing

| Surface | URL / path |
|---------|------------|
| Hosted iframe | `https://app.inference.sh/embed/agents/{namespace}/{name}` |
| Embed API | `GET /embed/agents/{namespace}/{name}`, `POST /embed/agents/run`, … |

See [Embed API](/docs/api/rest/embed) for anonymous chat endpoints and [Publishing](/docs/agents/publishing) for origin rules and host-page context.

---

## Related

- [Publishing and embedding agents](/docs/agents/publishing)
- [Embed API](/docs/api/rest/embed)
- [Agents API](/docs/api/rest/agents)