Messages

POST https://api.paperinstruments.com/v1/messages
x-api-key: $PAPERINSTRUMENTS_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json

The endpoint accepts the Anthropic Messages format with the parameters listed below. Authenticate with x-api-key or Authorization: Bearer. If you send both, they must match.

Anthropic SDK

Set the base URL to https://api.paperinstruments.com.

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.paperinstruments.com",
    api_key=os.environ["PAPERINSTRUMENTS_API_KEY"],
)

with client.messages.stream(
    model="ultramarine-1-flash",
    max_tokens=8192,
    messages=[{"role": "user", "content": "Explain EBITDA."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Claude Agent SDK and Claude Code

Set these environment variables:

These settings return 400:

Any model name other than ultramarine-1-flash returns 404.

In Claude Code, WebSearch does not work and reading a PDF returns an error.

import asyncio
import os
from claude_agent_sdk import ClaudeAgentOptions, query

ENV = {
    "ANTHROPIC_BASE_URL": "https://api.paperinstruments.com",
    "ANTHROPIC_API_KEY": os.environ["PAPERINSTRUMENTS_API_KEY"],
    "ANTHROPIC_MODEL": "ultramarine-1-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "ultramarine-1-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "ultramarine-1-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "ultramarine-1-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "ultramarine-1-flash",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
}


async def main():
    options = ClaudeAgentOptions(
        model="ultramarine-1-flash", env=ENV, allowed_tools=["Read", "Grep"]
    )
    async for message in query(prompt="Summarize README.md.", options=options):
        print(message)


asyncio.run(main())

For the Claude Code CLI, export the same variables and run claude --model ultramarine-1-flash.

Parameters

Tool names use 1 to 64 letters, digits, _, or -. Request bodies can be up to 20 MiB.

Content

A request can include up to 16 images. Each image can be up to 10 MiB and 32 million pixels, and cannot be animated.

Return one tool_result for each tool_use, before any other content in that user turn.

To add a system message mid-conversation, send anthropic-beta: mid-conversation-system-2026-04-07 and include a {"role": "system"} text turn after a user turn.

Headers

Conversation caching

The x-session-id header is optional. You can use it if you want sticky routing. When using it, reuse the same value for every turn, retry, and tool result in a conversation, and use a different value for each conversation.

Pass extra_headers={"x-session-id": "your-conversation-id"} in the Python Anthropic SDK, or { headers: { "x-session-id": "your-conversation-id" } } as the second argument to messages.create or messages.stream in Node.js.

Keep repeated prompt prefixes stable. Cache hits depend on matching prefixes and cache availability. Send the full message history on each request.

Not supported

Stop sequences (stop_sequences) are not currently supported.

These return 400 invalid_request_error. The error message names the field.

Token counting, Message Batches, the Files API, and the Models API are not available.

Errors

Errors use the Anthropic error format and include a request_id:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "thinking.type: Disabling thinking is not supported."
  },
  "request_id": "req_..."
}

See Errors for retries.