Opper REST API

Call the Opper platform directly via HTTP for task completion, knowledge bases, streaming, and observability.

Authentication

All requests require a Bearer token:

Authorization: Bearer $OPPER_API_KEY

Get your API key from platform.opper.ai.

Base URL

https://api.opper.ai

Core Endpoint: Task Completion

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

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:

{
  "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
  }
}

Request Fields

Streaming

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

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"}

Model Selection

Specify any supported model:

{
  "name": "task",
  "instructions": "...",
  "input": "...",
  "model": "anthropic/claude-4-sonnet"
}

With fallback chain:

{
  "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.

Few-Shot Examples

Guide model behavior with examples:

{
  "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"}
  ]
}

Structured Output with JSON Schema

The output_schema field accepts standard JSON Schema:

{
  "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).

Tracing

Create spans to group related operations:

# 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"
  }'

Knowledge Bases

Create and query semantic search indexes:

# 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}'

Error Handling

All errors return JSON with detail and appropriate HTTP status:

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

Common Mistakes

• Missing name field: Every call requires a unique name for tracking.
• Wrong auth header: Use Authorization: Bearer <key>, 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.

Additional Resources

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

Related Skills

• 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.

Upstream Sources

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