opper-api

All requests require a Bearer token:

```bash

Authorization: Bearer $OPPER_API_KEY

```

Get your API key from [platform.opper.ai](https://platform.opper.ai).

```

https://api.opper.ai

```

POST /v2/call — The primary endpoint. Describe a task and get structured results.

```bash

curl -X POST https://api.opper.ai/v2/call \

-H "Authorization: Bearer $OPPER_API_KEY" \

-H "Content-Type: application/json" \

-d '{

"name": "extract_entities",

"instructions": "Extract named entities from the text",

"input": "Tim Cook announced Apple'\''s new office in Austin, Texas.",

"output_schema": {

"type": "object",

"properties": {

"people": {"type": "array", "items": {"type": "string"}},

"locations": {"type": "array", "items": {"type": "string"}},

"organizations": {"type": "array", "items": {"type": "string"}}

},

"required": ["people", "locations", "organizations"]

}

}'

```

Response:

```json

{

"span_id": "550e8400-e29b-41d4-a716-446655440000",

"json_payload": {

"people": ["Tim Cook"],

"locations": ["Austin", "Texas"],

"organizations": ["Apple"]

},

"cached": false,

"usage": {

"input_tokens": 45,

"output_tokens": 28,

"total_tokens": 73

},

"cost": {

"total": 0.00012,

"generation": 0.0001,

"platform": 0.00002

}

}

```

| Field | Required | Description |

|-------|----------|-------------|

| name | Yes | Unique task identifier (used for tracking and auto-creating functions) |

| instructions | No | What the model should do |

| input | No | The input data (string, object, or any JSON) |

| input_schema | No | JSON Schema validating the input |

| output_schema | No | JSON Schema for structured output |

| model | No | Model name or array of fallbacks (e.g., "anthropic/claude-4-sonnet") |

| examples | No | Few-shot examples: [{"input": ..., "output": ..., "comment": ...}] |

| parent_span_id | No | UUID to link this call to a parent trace span |

| tags | No | Key-value metadata for filtering and cost attribution |

POST /v2/call/stream — Server-Sent Events for real-time token output.

```bash

curl -X POST https://api.opper.ai/v2/call/stream \

-H "Authorization: Bearer $OPPER_API_KEY" \

-H "Content-Type: application/json" \

-H "Accept: text/event-stream" \

-d '{

"name": "write_story",

"instructions": "Write a short story",

"input": "a robot learning to paint"

}'

```

SSE Response:

```

data: {"delta": "Once", "chunk_type": "text"}

data: {"delta": " upon", "chunk_type": "text"}

data: {"delta": " a time", "chunk_type": "text"}

data: {"delta": "", "span_id": "...", "chunk_type": "text"}

```

Specify any supported model:

```json

{

"name": "task",

"instructions": "...",

"input": "...",

"model": "anthropic/claude-4-sonnet"

}

```

With fallback chain:

```json

{

"model": ["anthropic/claude-4-sonnet", "openai/gpt-4o"]

}

```

Common models: openai/gpt-4o, openai/gpt-4o-mini, anthropic/claude-4-sonnet, anthropic/claude-4-opus, google/gemini-2.5-pro.

Guide model behavior with examples:

```json

{

"name": "classify",

"instructions": "Classify the support ticket",

"input": "My payment failed",

"examples": [

{"input": "Can't log in", "output": "auth", "comment": "Login issues"},

{"input": "Wrong charge", "output": "billing"}

]

}

```

The output_schema field accepts standard JSON Schema:

```json

{

"output_schema": {

"type": "object",

"properties": {

"sentiment": {

"type": "string",

"enum": ["positive", "negative", "neutral"]

},

"confidence": {

"type": "number",

"minimum": 0,

"maximum": 1

},

"keywords": {

"type": "array",

"items": {"type": "string"},

"maxItems": 5

}

},

"required": ["sentiment", "confidence"]

}

}

```

When output_schema is provided, the response uses json_payload. Without it, the response uses message (plain string).

Create spans to group related operations:

```bash

# Create a parent span

curl -X POST https://api.opper.ai/v2/spans \

-H "Authorization: Bearer $OPPER_API_KEY" \

-H "Content-Type: application/json" \

-d '{"name": "my_pipeline"}'

# Use the span_id as parent for subsequent calls

curl -X POST https://api.opper.ai/v2/call \

-H "Authorization: Bearer $OPPER_API_KEY" \

-H "Content-Type: application/json" \

-d '{

"name": "step_one",

"instructions": "...",

"input": "...",

"parent_span_id": "SPAN_ID_FROM_ABOVE"

}'

```

Create and query semantic search indexes:

```bash

# Create a knowledge base

curl -X POST https://api.opper.ai/v2/knowledge \

-H "Authorization: Bearer $OPPER_API_KEY" \

-H "Content-Type: application/json" \

-d '{"name": "support_docs"}'

# Add a document

curl -X POST https://api.opper.ai/v2/knowledge/{id}/add \

-H "Authorization: Bearer $OPPER_API_KEY" \

-H "Content-Type: application/json" \

-d '{

"key": "doc1",

"content": "To reset your password, click Forgot Password.",

"metadata": {"category": "auth"}

}'

# Query

curl -X POST https://api.opper.ai/v2/knowledge/{id}/query \

-H "Authorization: Bearer $OPPER_API_KEY" \

-H "Content-Type: application/json" \

-d '{"query": "How to reset password?", "top_k": 3}'

```

All errors return JSON with detail and appropriate HTTP status:

| Status | Meaning |

|--------|---------|

| 400 | Bad request / invalid input |

| 401 | Missing or invalid API key |

| 404 | Resource not found |

| 422 | Validation error |

| 502 | Upstream LLM provider error |

```json

{"detail": "Invalid output_schema: ..."}

```

• Missing name field: Every call requires a unique name for tracking.
• Wrong auth header: Use Authorization: Bearer , not X-API-Key or similar.
• No output_schema but expecting JSON: Without a schema, you get a plain string in message.
• Forgetting required in schemas: JSON Schema fields are optional by default.
• Not checking json_payload vs message: Structured calls use json_payload; unstructured use message.

• For the complete endpoint catalog, see [references/ENDPOINTS.md](references/ENDPOINTS.md)
• For knowledge base operations, see [references/KNOWLEDGE.md](references/KNOWLEDGE.md)
• For tracing and spans, see [references/TRACING.md](references/TRACING.md)
• For migrating from OpenRouter, see [references/MIGRATION.md](references/MIGRATION.md)

• opper-python-sdk: Use when building in Python — provides a higher-level client wrapping this API.
• opper-node-sdk: Use when building in TypeScript — provides a typed client wrapping this API.
• opper-python-agents: Use when you need autonomous agents, not just single API calls.
• opper-node-agents: Use when you need autonomous agents in TypeScript.
• opper-cli: Use when calling Opper functions from the terminal.

When this skill's content may be outdated, resolve using this priority:

1. API spec — fetch the live OpenAPI spec at https://api.opper.ai/v2/openapi.json for the current endpoint definitions
2. Documentation: https://docs.opper.ai