REST API

The REST API lets you manage files, execute tools, and check container status programmatically. Every MCP tool is available as an HTTP endpoint. It uses the same authentication and credit system as MCP.

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, only the status endpoint is accessible without authentication. All other endpoints (files, upload, delete, claim) require an API key or bearer token.

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.

See Authentication for details on obtaining credentials.

Endpoints

Get Container Status

GET /container/:id/status

Returns the container’s current state: initialization status, tool count, entry count, file processing stats, and analysis state. This is the only endpoint accessible on public containers without authentication.

Example request:

curl -H "x-api-key: YOUR_API_KEY" \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/status

Example response:

{
  "success": true,
  "data": {
    "containerId": "abc123",
    "containerName": "My Container",
    "is_ephemeral": false,
    "initialized": true,
    "initializationStatus": "complete",
    "paused": false,
    "ready": true,
    "counts": {
      "tools": 5,
      "entries": 142,
      "entityTypes": 4,
      "files": 3
    },
    "files": {
      "total": 3,
      "pending": 0,
      "processing": 0,
      "completed": 3,
      "failed": 0
    },
    "analysis": {
      "inProgress": false,
      "cadence": "automatic"
    }
  }
}

Field	Description
ready	true when the container is initialized, complete, and not paused
initializationStatus	One of: pending, analyzing, generating_tools, complete
counts.tools	Number of active MCP tools
counts.entries	Total entries in the container
counts.entityTypes	Number of discovered entity types
files	Breakdown of file processing status
analysis.inProgress	Whether an analysis pass is currently running

List Files

GET /container/:id/files

Returns all files uploaded to the container. Requires authentication (no public access).

Example request:

curl -H "x-api-key: YOUR_API_KEY" \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/files

Example response:

{
  "success": true,
  "data": [
    {
      "id": "file_abc123",
      "name": "document.pdf",
      "size": 245760,
      "mimeType": "application/pdf",
      "uploadedAt": "2026-03-30T12:00:00Z",
      "createdAt": "2026-03-30T12:00:00Z"
    }
  ]
}

Upload File

POST /container/:id/files

Upload a file using multipart form data. Requires authentication (no public access).

Wire processes the file automatically after upload, extracting entries and building context.

Example request:

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@customers.csv" \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/files

See Supported File Types for the complete list of accepted formats.

Delete File

DELETE /container/:id/files/:fileId

Delete a file and all its associated entries. Requires authentication (no public access).

Example request:

curl -X DELETE \
  -H "x-api-key: YOUR_API_KEY" \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/files/file_abc123

Tool Endpoints

Every MCP tool is also available as a REST endpoint. These use the same underlying execution engine and credit system as MCP. All tool endpoints accept POST with a JSON body.

Credit costs match MCP: 1 credit per tool call, 5 credits for semantic search mode. See Tools Reference for detailed parameter documentation.

Note

REST tool endpoints use the 5 default tools (wire_explore, wire_search, wire_write, wire_delete, wire_analyze). Tool active/inactive status in the dashboard is enforced across both MCP and REST. Deactivating a tool blocks it from being called via either channel.

Explore

POST /container/:id/tools/explore

Discover entity types, fields, relationships, and entry counts. Call this first to understand a container’s schema before searching.

Parameter	Type	Required	Description
entityType	string	No	Drill into a specific entity type for detailed schema and samples
includeSamples	boolean	No	Include sample entries (only with entityType). Default false.
sampleLimit	number	No	Number of samples (1-10). Default 3.

Example request:

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/tools/explore

Example response:

{
  "success": true,
  "data": {
    "totalEntityTypes": 3,
    "totalEntries": 142,
    "entityTypes": [
      { "name": "Customer", "entryCount": 89, "fields": [{ "name": "email", "type": "string" }] }
    ],
    "relationships": [["Customer", "orderId", "Order"]]
  }
}

Search

POST /container/:id/tools/search

Query data using five modes: list, get, filter, text, or semantic. Same capabilities as the wire_search MCP tool.

Parameter	Type	Required	Description
mode	string	Yes	One of: list, get, filter, text, semantic
entityType	string	Depends	Required for list, filter, text modes
query	string	Depends	Required for text and semantic modes
id	string	Depends	Required for get mode
filters	array	No	Field conditions for filter mode
limit	number	No	Max results (default varies by mode)
offset	number	No	Pagination offset
include	string[]	No	Related entity types to resolve

Example request (semantic search):

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

Example request (list mode):

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "list", "entityType": "Customer", "limit": 10}' \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/tools/search

Write

POST /container/:id/tools/write

Save a new entry to the container. Requires authentication (not available on public containers).

Parameter	Type	Required	Description
content	string or object	Yes	Text/markdown string or structured data object
tags	string[]	No	Tags for lightweight filtering
metadata	object	No	Key-value metadata stored in entry properties
source	string	No	Source label (default: "agent:mcp")

Example request:

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

Example response:

{
  "success": true,
  "data": {
    "entryId": "entry_abc123",
    "message": "Entry queued for storage. It will be searchable within a few seconds."
  }
}

Delete

POST /container/:id/tools/delete

Permanently delete an entry and clean up related graph data. Requires authentication (not available on public containers).

Parameter	Type	Required	Description
entryId	string	Yes	The entry ID to delete (returned by write)

Example request:

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entryId": "entry_abc123"}' \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/tools/delete

Analyze

POST /container/:id/tools/analyze

Trigger a re-analysis of the container to discover entity types, build relationships, and refresh search capabilities. Requires authentication (not available on public containers).

Takes no parameters (empty JSON body).

Example request:

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/tools/analyze

Example response:

{
  "success": true,
  "data": {
    "message": "Analysis triggered",
    "workflowId": "wf_abc123"
  }
}

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.

Example request:

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

Example response:

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

Error Responses

All errors follow the same format:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Unknown endpoint: GET /unknown"
  }
}

Code	HTTP Status	Description
BAD_REQUEST	400	Missing required parameter
UNAUTHORIZED	401	Missing or invalid credentials
FORBIDDEN	403	Action not allowed (e.g., write tools on public access)
INSUFFICIENT_CREDITS	402	Not enough credits to execute tool
NOT_FOUND	404	Container or file not found
TOOL_ERROR	422	Tool execution returned an error
CONFLICT	409	Container already claimed
INTERNAL_ERROR	500	Server error

Next Steps

• Authentication — OAuth and API key details
• Tools Reference — MCP tool documentation
• Supported File Types — Accepted upload formats