HTTP API Reference

This page documents all HTTP endpoints in the Open Reward Standard protocol.

Base URL

All endpoints are relative to the ORS server base URL:

http://localhost:8080         # Local development
https://your-server.com       # Production

Common Headers

X-Session-ID

Most endpoints require the X-Session-ID header to identify the episode:

X-Session-ID: abc-123-def-456

Required for: /create, /delete, /ping, /{env_name}/call, /{env_name}/prompt Not required for: /create_session, discovery endpoints, /health

Discovery Endpoints

These endpoints provide information about available environments, tools, and tasks. They do not require authentication or session IDs.

GET /health

Health check endpoint. Request:

GET /health

Response (200 OK):

{
  "status": "ok"
}

Use case: Verify server is running and responsive.

GET /list_environments

List all available environments on this server. Request:

GET /list_environments

Response (200 OK):

[
  "math",
  "code_env",
  "web_nav"
]

Returns an array of environment names (strings). Each name can be used in /{env_name}/* endpoints. Use case: Discover what environments are available before creating a session.

GET //tools

List all tools available in the specified environment. Request:

GET /math/tools

Response (200 OK):

{
  "tools": [
    {
      "name": "submit",
      "description": "Submit an answer to the math problem",
      "input_schema": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "string",
            "description": "Your answer to the problem"
          }
        },
        "required": ["answer"]
      }
    }
  ]
}

Response Schema:

tools: Array of ToolSpec objects
- name: Tool identifier (string)
- description: Human-readable description (string)
- input_schema: JSON Schema defining tool parameters (object, optional)

Error Responses:

404 Not Found: Environment name not recognized

Use case: Discover what actions the agent can take before starting an episode.

GET //splits

List all task splits available in the environment. Request:

GET /math/splits

Response (200 OK):

[
  {
    "name": "train",
    "type": "train"
  },
  {
    "name": "test",
    "type": "test"
  }
]

Response Schema:

Array of Split objects
- name: Split identifier (string)
- type: Split category - “train”, “validation”, or “test” (string)

Error Responses:

404 Not Found: Environment name not recognized

Use case: Determine which task sets are available for training vs evaluation.

POST //tasks

List tasks for a specific split. Request:

POST /math/tasks
Content-Type: application/json

{
  "split": "train"
}

Request Schema:

split: Split name to query (string, required)

Response (200 OK):

{
  "tasks": [
    {
      "question": "What is 2+2?",
      "answer": "4"
    },
    {
      "question": "If x + 5 = 12, what is x?",
      "answer": "7"
    }
  ],
  "env_name": "math"
}

Response Schema:

tasks: Array of task objects (structure is environment-specific)
env_name: Environment name (string)

Error Responses:

400 Bad Request: Invalid split name
404 Not Found: Environment name not recognized

Use case: Get the list of tasks to iterate through during training or evaluation. Note: Task structure is environment-specific. Math environments have questions and answers. Coding environments have problem descriptions and test cases.

Session Management

These endpoints manage episode lifecycle.

POST /create_session

Generate a new session ID. Request:

POST /create_session

Response (200 OK):

{
  "sid": "abc-123-def-456"
}

Response Schema:

sid: Session identifier (string, UUID format)

Use case: First step in episode lifecycle. Get a session ID to use in subsequent requests. Note: This endpoint only generates an ID. The episode instance is created by /create.

POST /create

Create an episode instance for a specific task. Request:

POST /create
X-Session-ID: abc-123-def-456
Content-Type: application/json

{
  "env_name": "math",
  "task_spec": {
    "question": "What is 2+2?",
    "answer": "4"
  },
  "secrets": {
    "api_key": "sk-..."
  }
}

Request Headers:

X-Session-ID: Session identifier from /create_session (required)

Request Schema:

env_name: Environment to instantiate (string, required)
task_spec: Task-specific data (object, required)
secrets: Secrets to pass to environment (object, optional, default: )

Response (200 OK):

{
  "sid": "abc-123-def-456"
}

Error Responses:

400 Bad Request: Session already exists, or missing X-Session-ID header
404 Not Found: Environment name not recognized

Use case: Start an episode by initializing the environment with a specific task. This calls the environment’s setup() method. Important: The environment initialization happens asynchronously. Subsequent requests wait for setup to complete.

POST /ping

Keep the session alive to prevent timeout. Request:

POST /ping
X-Session-ID: abc-123-def-456

Request Headers:

X-Session-ID: Session identifier (required)

Response (200 OK):

{
  "status": "ok"
}

Error Responses:

400 Bad Request: Missing X-Session-ID header
404 Not Found: Session not found

Use case: Sessions timeout after 15 minutes of inactivity. Call /ping periodically (e.g., every 5 minutes) to keep the session alive.

POST /delete

Delete an episode and clean up resources. Request:

POST /delete
X-Session-ID: abc-123-def-456

Request Headers:

X-Session-ID: Session identifier (required)

Response (200 OK):

{
  "sid": "abc-123-def-456"
}

Error Responses:

400 Bad Request: Missing X-Session-ID header
404 Not Found: Session not found

Use case: Clean up after episode completes. This calls the environment’s teardown() method. Important: Always call /delete when done with an episode to free server resources.

POST /delete_session

Optional cleanup endpoint for session ID. Request:

POST /delete_session
X-Session-ID: abc-123-def-456

Request Headers:

X-Session-ID: Session identifier (required)

Response (200 OK):

{
  "sid": "abc-123-def-456"
}

Use case: Optional cleanup after /delete. In practice, /delete is sufficient.

Episode Interaction

These endpoints interact with an active episode.

GET //prompt

Get the initial prompt for the current task. Request:

GET /math/prompt
X-Session-ID: abc-123-def-456

Request Headers:

X-Session-ID: Session identifier (required)

Response (200 OK):

[
  {
    "text": "What is 2+2?",
    "detail": null,
    "type": "text"
  }
]

Response Schema:

Array of Block objects
- TextBlock: {"text": "...", "detail": null, "type": "text"}
- ImageBlock: {"data": "base64...", "mimeType": "image/png", "detail": null, "type": "image"}

Error Responses:

400 Bad Request: Missing X-Session-ID header
404 Not Found: Session not found or environment name mismatch
410 Gone: Session was deleted

Use case: Get the initial state/instructions for the episode. Call this after /create and before calling tools. Note: Prompts can be multi-modal (text + images).

POST //call

Call a tool in the environment. Request:

POST /math/call
X-Session-ID: abc-123-def-456
Accept: text/event-stream
Content-Type: application/json

{
  "name": "submit",
  "input": {
    "answer": "4"
  },
  "task_id": "optional-trace-id"
}

Request Headers:

X-Session-ID: Session identifier (required)
Accept: Must be text/event-stream (required for SSE)

Request Schema:

name: Tool name to call (string, required)
input: Tool-specific parameters (object, required)
task_id: Optional ID for tracing (string, optional)

Response (200 OK - Server-Sent Events):

event: task_id
data: 877bb56c594e4a0f921ad55c439a3762

event: end
data: {"ok": true, "output": {"blocks": [{"text": "Correct!", "detail": null, "type": "text"}], "metadata": null, "reward": 1.0, "finished": true}}

Response Schema (SSE data field): On success:

{
  "ok": true,
  "output": {
    "blocks": [
      {"text": "Tool output", "detail": null, "type": "text"}
    ],
    "metadata": null,
    "reward": 1.0,
    "finished": true
  }
}

On error:

{
  "ok": false,
  "error": "Error message"
}

Error Responses:

400 Bad Request: Missing X-Session-ID, invalid tool name, or invalid input
404 Not Found: Session not found, environment mismatch, or tool not found
410 Gone: Session was deleted

Use case: Execute an action in the environment. This is the core interaction loop. Important:

Responses are streamed via Server-Sent Events (see Tool Execution with SSE section above)
The finished field indicates if the episode is complete
The reward field provides RL feedback signal

Complete Episode Flow

Here’s a complete example showing all endpoints in sequence:

# 1. Health check
curl http://localhost:8080/health
# → {"status": "ok"}

# 2. List environments
curl http://localhost:8080/list_environments
# → ["math"]

# 3. List tools
curl http://localhost:8080/math/tools
# → {"tools": [{"name": "submit", ...}]}

# 4. List splits
curl http://localhost:8080/math/splits
# → [{"name": "train", "type": "train"}, ...]

# 5. List tasks
curl -X POST http://localhost:8080/math/tasks \
  -H "Content-Type: application/json" \
  -d '{"split": "train"}'
# → {"tasks": [...], "env_name": "math"}

# 6. Create session ID
curl -X POST http://localhost:8080/create_session
# → {"sid": "abc-123"}

# 7. Create episode
curl -X POST http://localhost:8080/create \
  -H "X-Session-ID: abc-123" \
  -H "Content-Type: application/json" \
  -d '{"env_name": "math", "task_spec": {"question": "What is 2+2?"}, "secrets": {}}'
# → {"sid": "abc-123"}

# 8. Get prompt
curl http://localhost:8080/math/prompt \
  -H "X-Session-ID: abc-123"
# → [{"text": "What is 2+2?", "detail": null, "type": "text"}]

# 9. Call tool (SSE response)
curl -X POST http://localhost:8080/math/call \
  -H "X-Session-ID: abc-123" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"name": "submit", "input": {"answer": "4"}}'
# → SSE stream with result

# 10. Delete episode
curl -X POST http://localhost:8080/delete \
  -H "X-Session-ID: abc-123"
# → {"sid": "abc-123"}

Error Handling

Standard HTTP Status Codes

200 OK: Request succeeded
400 Bad Request: Invalid input (missing header, invalid JSON, etc.)
404 Not Found: Resource not found (environment, session, tool)
410 Gone: Session was deleted
500 Internal Server Error: Server error during processing

Error Response Format

For HTTP errors (non-SSE):

{
  "detail": "Error message explaining what went wrong"
}

For tool execution errors (SSE):

{
  "ok": false,
  "error": "Tool execution failed: reason"
}

Rate Limiting and Timeouts

Session Timeout

Sessions automatically expire after 15 minutes of inactivity:

“Activity” means any request with that session’s X-Session-ID
Use /ping to keep sessions alive
Timeout is reset after each request

Request Timeout

Individual requests may have server-specific timeouts. Long-running tool calls should use SSE streaming to avoid timeouts.

Next Steps

Data Types

Detailed schemas for all request/response objects

Implementing a Client

Build an ORS client using these endpoints

Implementing a Server

Build an ORS server that implements these endpoints

Reference Implementation: The OpenReward Python SDK implements this complete API. See the server.py source for implementation details.

Getting Started

Specification

Core Concepts

Implementation Guides

Comparison

HTTP API Reference

HTTP API Reference

Base URL

Common Headers

X-Session-ID

Discovery Endpoints

GET /health

GET /list_environments

GET //tools

GET //splits

POST //tasks

Session Management

POST /create_session

POST /create

POST /ping

POST /delete

POST /delete_session

Episode Interaction

GET //prompt

POST //call

Complete Episode Flow

Error Handling

Standard HTTP Status Codes

Error Response Format

Rate Limiting and Timeouts

Session Timeout

Request Timeout

Next Steps

Data Types

Implementing a Client

Implementing a Server

Getting Started

Specification

Core Concepts

Implementation Guides

Comparison

​HTTP API Reference

​Base URL

​Common Headers

​X-Session-ID

​Discovery Endpoints

​GET /health

​GET /list_environments

​GET //tools

​GET //splits

​POST //tasks

​Session Management

​POST /create_session

​POST /create

​POST /ping

​POST /delete

​POST /delete_session

​Episode Interaction

​GET //prompt

​POST //call

​Complete Episode Flow

​Error Handling

​Standard HTTP Status Codes

​Error Response Format

​Rate Limiting and Timeouts

​Session Timeout

​Request Timeout

​Next Steps

Data Types

Implementing a Client

Implementing a Server

HTTP API Reference

Base URL

Common Headers

X-Session-ID

Discovery Endpoints

GET /health

GET /list_environments

GET //tools

GET //splits

POST //tasks

Session Management

POST /create_session

POST /create

POST /ping

POST /delete

POST /delete_session

Episode Interaction

GET //prompt

POST //call

Complete Episode Flow

Error Handling

Standard HTTP Status Codes

Error Response Format

Rate Limiting and Timeouts

Session Timeout

Request Timeout

Next Steps