> ## Documentation Index
> Fetch the complete documentation index at: https://developers.apob.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP and JSON-RPC

> Use APOB's stateless Streamable HTTP endpoint, discover tools and resources, and distinguish protocol and tool errors.

## HTTP contract

Send a single JSON-RPC message per `POST` to `APOB_MCP_URL`. The current server
supports MCP versions `2025-03-26`, `2025-06-18`, and `2025-11-25`; the examples
use `2025-11-25`. Use the version returned by initialization for later requests.

| Header or limit | Contract |
| - | - |
| `Authorization` | `Bearer <MCP_ACCESS_TOKEN>` from the [OAuth flow](/mcp/authentication). |
| `Content-Type` | `application/json`. |
| `Accept` | Include both `application/json` and `text/event-stream`. |
| `MCP-Protocol-Version` | Send the negotiated version on requests after initialization. Unsupported or duplicate values are rejected. |
| `Origin` | If supplied, exactly match the configured MCP resource's scheme, host, and port. Duplicate or other origins are rejected. |
| Body size | At most 16 KiB; upload bytes directly using the [upload flow](/mcp/uploads-and-live). |

The endpoint is stateless: it does not issue or require `Mcp-Session-Id`. `GET`
and `DELETE` return `405`; there is no standalone SSE subscription at `/mcp`.
Successful request responses use JSON. Accepted notifications return `202`
with an empty body. The `Accept` requirement follows the
[Streamable HTTP transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports).

## Initialize

```bash theme={null}
curl "$APOB_MCP_URL" \
  -H "Authorization: Bearer $MCP_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"example-client","version":"1.0.0"}}}'
```

Inspect `result.protocolVersion`, `result.serverInfo`, and `result.capabilities`.
APOB advertises tools and resources; it does not advertise prompts, tool-list
change notifications, or resource subscriptions. Then send the notification:

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
```

## Discover tools and call one

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

Each tool supplies its name, description, `inputSchema`, and annotations.
Generation schemas include account-specific defaults. Preserve schema conditions
and explicit user choices; see the [tool catalog](/mcp/tools).

The tool name belongs in `params.name`, and its inputs in `params.arguments`:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_personal_models",
    "arguments": { "pageNumber": 1, "pageSize": 10 }
  }
}
```

Use a distinct JSON-RPC request ID to correlate each response. That ID does not
make a creation or payment call idempotent.

## Read the image prompt resource

`resources/list` exposes `apob://docs/image-prompt-format/v1`, a Markdown guide
to the tagged prompt required by `create_image`. Read it before constructing a
request; resource discovery alone does not insert its rules into a host's prompt.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": { "uri": "apob://docs/image-prompt-format/v1" }
}
```

The response has `result.contents` entries with `uri`, `mimeType`, and `text`.
Ordinary video and editing tools use their own prompt contracts rather than
the `create_image` tags.

## Results

Successful tool calls return `result.structuredContent` and the same JSON
serialized into a text entry in `result.content`. Interpret the tool's fields
and `isError` before treating a call as successful. A generation receipt is
an accepted submission; poll `get_generation_result` for finished media.

## Errors

| Layer | Examples | What to do |
| - | - | - |
| HTTP authentication | `401` with Bearer challenge for missing, invalid, expired, or revoked credentials; `403` for insufficient scope. | Inspect `WWW-Authenticate`, authorize the expected account, and request `mcp:access`. |
| HTTP request | `400` unsupported protocol version or invalid Accept header, `403` invalid Origin, `405` unsupported method, `413` oversized body, `415` non-JSON content type. Malformed JSON or unsupported methods can also fail at transport level. | Correct the request. Authentication can reject it before transport validation. |
| JSON-RPC | Top-level `error` for unknown tool/resource requests or tool-discovery account lookup failure. | Inspect the error and correct the request or retry a read as appropriate. |
| Tool | `result.isError: true` for input-schema validation or a tool's public error code/message. | Follow the specific tool's recovery guidance. HTTP `200` alone is not success. |

An authentication storage outage fails closed with a retryable HTTP `503`.
A lost response or a transport failure after a write can leave the outcome
uncertain. Follow [generation errors](/mcp/generation#results-and-errors) or
[billing reconciliation](/mcp/billing), and do not automatically repeat paid work.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.