# REST API

REST is one of two transports for invoking tools on a Wire container. The other is [MCP](/mcp/overview/). What tools exist, what they do, and what they return is defined on the [Tools page](/reference/tools/) — this page covers how to call them over HTTP.

## Base URL

<PersonalizedCode
  client:load
  code="https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID"
  title="Your Container's REST API Base URL"
/>

## Authentication

All REST endpoints accept the same credentials as MCP:

- **API Key**: `x-api-key: YOUR_API_KEY` header
- **Bearer Token**: `Authorization: Bearer YOUR_TOKEN` header

On [public containers](/guides/public-containers/), `wire_status` (`GET /status`) is accessible without authentication. All other tools require an API key or bearer token.

:::tip[Container-scoped keys are enforced on REST too]
Create keys from the container's **Access** tab so the key only works for that one container. If a scoped key is used against a different container's REST endpoint, Wire returns `403 Forbidden` — the same enforcement that applies to MCP. See [Authentication](/mcp/authentication/#container-scoped-keys-recommended).
:::

See [Authentication](/mcp/authentication/) for details on obtaining credentials.

## Calling tools

REST exposes two endpoint styles:

**1. Generic tool dispatcher** — for the standard tools (`wire_explore`, `wire_search`, `wire_navigate`, `wire_write`, `wire_delete`):

```
POST /container/:id/tools/{short-name}
```

The `{short-name}` is the tool name without the `wire_` prefix. The request body is a JSON object matching the tool's input schema documented on the [Tools page](/reference/tools/).

**Example:**

```bash
curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "customer feedback on pricing"}' \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/tools/search
```

**2. Dedicated REST endpoints** — for file and status tools, where the underlying operation doesn't map cleanly to a JSON-body call (multipart upload, GET semantics for status, path-positional file IDs):

| Tool | REST endpoint |
|---|---|
| `wire_status` | `GET /container/:id/status` |
| `wire_files_list` | `GET /container/:id/files` |
| `wire_files_upload` | `POST /container/:id/files` (multipart) |
| `wire_files_delete` | `DELETE /container/:id/files/:fileId` |

Both styles share the same gating: if a tool is toggled off for the REST transport on the container's Tools page, the corresponding endpoint returns `404 NOT_FOUND`. See [Tools](/reference/tools/) for each tool's input schema, output shape, default visibility, and credit cost.

### Webhook source pattern

Any automation platform that can make an authenticated HTTP POST — **n8n, Zapier, Make, Pipedream, a cron job, a shell script** — can drop entries into a Wire container by calling `wire_write`:

```bash
curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Q2 revenue increased 15% driven by enterprise segment", "tags": ["finance", "q2"]}' \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/tools/write
```

Wire uses the `source` string to trace where each entry came from. Stick to the `<platform>:<identifier>` pattern so downstream graph exploration stays tidy:

| Origin | Recommended `source` |
|--------|----------------------|
| Claude Code / other MCP agents | `agent:session-abc` (default: `agent:mcp`) |
| REST without explicit `source` | `webhook:<api-key-name>` (auto-filled) |
| n8n workflow | `n8n:<workflow-id>:<node-id>` |
| Make scenario | `make:<scenario-id>` |
| Zapier zap | `zapier:<zap-id>` |
| Custom script / anything else | `webhook:<descriptive-name>` |

See the **Sources tab** inside any container in the dashboard to grab the endpoint URL pre-filled for your container.

## Other endpoints

### Claim ephemeral container

```
POST /container/:id/claim
```

Generate a claim link for an ephemeral container. Returns a URL the user can open to sign up or log in and make the container permanent. Requires authentication.

Returns `409 Conflict` if the container has already been claimed.

```bash
curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/claim
```

```json
{
  "success": true,
  "data": {
    "claim_url": "https://app.usewire.io/onboarding/create-account?claimToken=...",
    "expires_in": 3600
  }
}
```

## Error responses

All errors follow the same format:

```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Endpoint disabled: 'wire_files_list' is turned off for this container's REST transport"
  }
}
```

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `BAD_REQUEST` | 400 | Missing required parameter |
| `UNAUTHORIZED` | 401 | Missing or invalid credentials |
| `INSUFFICIENT_CREDITS` | 402 | Not enough credits to execute tool |
| `FORBIDDEN` | 403 | Action not allowed (e.g., write tools on public access, scoped key on wrong container) |
| `NOT_FOUND` | 404 | Container, file, or tool not found — also returned when a tool is toggled off for the REST transport |
| `CONFLICT` | 409 | Container already claimed |
| `TOOL_ERROR` | 422 | Tool execution returned an error |
| `INTERNAL_ERROR` | 500 | Server error |

## Next Steps

- [Tools Reference](/reference/tools/) — what each tool does, input schemas, defaults, costs
- [Authentication](/mcp/authentication/) — OAuth and API key details
- [Supported File Types](/reference/file-types/) — accepted upload formats