The Responses API

Autopoetic exposes an OpenAI Responses API-compatible endpoint: send a message, get a streamed response with perspective metadata — using the official OpenAI client libraries or plain HTTP.

This is the inference surface — the only API that generates agent responses. To manage conversations, knowledge, projects, and workflows as data (without generating), use the platform API; see the API overview for the full picture.

POST https://app.autopoetic.ai/api/openai_responses_compatible/v1/responses

Authentication

1. An admin creates an API key on the project's API Keys page (see projects and teams). The key — a long-lived access token — is shown exactly once; copy it before leaving the page.

2. Send it as a bearer token on every request:

   Authorization: Bearer YOUR_API_KEY
   

API keys carry the project's admin role. The Responses endpoint always requires a valid token.

Quick start

curl -X POST \
  https://app.autopoetic.ai/api/openai_responses_compatible/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "autopoetic-agent-humanist-0.0.5.en",
    "input": [
      {"type": "message", "role": "user", "content": "Hello!"}
    ],
    "store": true
  }'

Every response — this endpoint included — is a stream of SSE events (text/event-stream), even if you don't ask to stream. Keepalives are sent as SSE comment lines so proxies don't time out.

Request fields

Field	Required	Notes
model	yes	The agent to use — e.g. autopoetic-agent-humanist-0.0.5.en.
input	yes	A string, or a list of message items with role (system, developer, user, assistant) and content.
instructions	no	Prepended to the conversation context.
previous_response_id	no	Continue an existing conversation, format <conversation_uuid>/<message_uuid>. Omit to start a new conversation.
project_uuid	no	Pick which authorized project the request applies to.
store	no	Conversations are always persisted; this field is accepted for compatibility.
include	no	"perspectives" appends each perspective's analysis to the output.
tools	no	OpenAI-style function tools; calls surface as function_call output items.
reasoning	no	{"effort": "low"\|"medium"\|"high"} or {"enabled": true} enables thinking mode.

The last user message is the prompt (limit 32,000 tokens). Other OpenAI fields (stream, temperature, top_p, max_output_tokens, metadata, …) are accepted for compatibility and ignored.

Response events

The SSE stream emits OpenAI Responses-style events:

• response.created — the response object (status: in_progress).
• response.output_item.added / response.output_item.done — items as they start and finish: perspective reasoning items (persp-…, only when include: ["perspectives"]), the message, and function calls.
• response.reasoning_summary_text.delta — streaming tokens for each perspective's analysis.
• response.output_text.delta — streaming tokens of the response message.
• response.function_call_arguments.delta / .done — tool-call arguments (tools mode).
• response.completed — the finished response with output and usage.
• response.failed — an in-stream pipeline failure, with an OpenAI-style error object.

The response id is <conversation_uuid>/<message_uuid> — pass it back as previous_response_id to continue that conversation. The usage object includes input_tokens, output_tokens, total_tokens, and gpu_ms, plus provider_metadata with each perspective's weight, its 3D position, and the steering magnitude for the message.

Usage limits

Requests over your plan's hard limit fail with HTTP 402 (hard_limit_exceeded); lapsed subscriptions get 402 (subscription_lapsed). Over the soft limit, requests are accepted but rate-limited. See pricing.

With the OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://app.autopoetic.ai/api/openai_responses_compatible/v1",
    api_key="YOUR_API_KEY",
)

stream = client.responses.create(
    model="autopoetic-agent-humanist-0.0.5.en",
    input="What do you think about deterministic finishing moves in chess?",
    stream=True,
    include=["perspectives"],
)

for event in stream:
    print(event.type)

Compatibility notes

• Responses are always streamed — stream: false is not honored.
• Conversations are always persisted — store: false is not honored.
• model names Autopoetic agents, not OpenAI models.
• Response IDs are conversation/message UUIDs, not resp_… strings.
• Errors follow the OpenAI envelope ({"error": {"type", "code", "message"}}); usage-limit errors use the custom type autopoetic_error.
• Prompt-injected function calling: tools are described to the agent in the prompt, calls are parsed from its output into standard function_call items.