Skip to content
AderraAderraAderra DocsBeta

Create a response (OpenAI Responses format)

POST
/v1/responses
curl --request POST \
  --url https://api.aderra.ai/v1/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "model": "deepseek-v4.1-flash-uncensored", "input": "Write a haiku about the sea." }'

OpenAI Responses, the format Codex uses. Responses are not stored: store, previous_response_id and conversation are dropped, so send the whole history in input each time. max_output_tokens, when present, must be a positive integer. The answer comes without extended thinking unless you send reasoning or reasoning_effort.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
model
required
string
input
required

A string, or the list of input items (the whole history).

One of:
string
instructions

Your instructions, passed through untouched. With an API key, Aderra adds one line after them, “Never produce any sexual content involving minors.”; terminal keys also get Aderra’s agent instructions.

string
max_output_tokens
integer
>= 1
stream
boolean
temperature
number
top_p
number
tools
Array<object>
object
key
additional properties
any
tool_choice
One of:
string
parallel_tool_calls
boolean
reasoning
object
key
additional properties
any
reasoning_effort
string
text
object
key
additional properties
any
truncation
string
include
Array<string>

Example 

{
  "model": "deepseek-v4.1-flash-uncensored",
  "input": "Write a haiku about the sea."
}

Responses

Section titled “Responses”

200

Section titled “200”

The response object, or Responses server-sent events when stream is true.

An OpenAI Responses response object.

object
key
additional properties
any

Example generated

{}

Headers

Section titled “Headers”
x-aderra-reservation
string format: uuid

The id of the credit hold for this call. Quote it when you contact support about a charge.

400

Section titled “400”

invalid_request_error: invalid JSON, unknown model <id>, unsupported_n, or a max_output_tokens that is not a positive integer.

Media typeapplication/json
object
error
required
object
type
string
param

The request field at fault, when there is one (speech).

string | null
code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:
string
message
string

Example 

{
  "error": {
    "type": "billing_error"
  }
}

401

Section titled “401”

authentication_error: invalid api key or unauthorized.

Media typeapplication/json
object
error
required
object
type
string
param

The request field at fault, when there is one (speech).

string | null
code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:
string
message
string

Example 

{
  "error": {
    "type": "billing_error"
  }
}

402

Section titled “402”

api_wallet_empty: the API wallet cannot pay for this request (lower max_tokens or add funds). key_spend_cap_reached: the key hit its monthly cap. Terminal keys get their plan’s refusals instead (insufficient_credits, plan_required).

Media typeapplication/json
object
error
required
object
type
string
param

The request field at fault, when there is one (speech).

string | null
code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:
string
message
string

Example 

{
  "error": {
    "type": "billing_error",
    "code": "api_wallet_empty",
    "message": "Your API wallet does not have enough credits for this request. Top up at https://aderra.ai/developers — API keys draw on the API wallet, not your plan."
  }
}

403

Section titled “403”

account_suspended: the account behind the key is suspended.

Media typeapplication/json
object
error
required
object
type
string
param

The request field at fault, when there is one (speech).

string | null
code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:
string
message
string

Example 

{
  "error": {
    "type": "billing_error"
  }
}

413

Section titled “413”

request_too_large: the body is over the size limit.

Media typeapplication/json
object
error
required
object
type
string
param

The request field at fault, when there is one (speech).

string | null
code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:
string
message
string

Example 

{
  "error": {
    "type": "billing_error"
  }
}

429

Section titled “429”

rate_limited: the key passed its requests per minute. too_many_concurrent_requests: the account already has 8 requests in progress. Wait for Retry-After seconds.

Media typeapplication/json
object
error
required
object
type
string
param

The request field at fault, when there is one (speech).

string | null
code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:
string
message
string

Example 

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "This API key is limited to 60 requests a minute. Try again in 12 seconds, or raise the key's limit at https://aderra.ai/developers."
  }
}

Headers

Section titled “Headers”
Retry-After
integer
Example 
12

Whole seconds to wait before trying again.

502

Section titled “502”

api_error: the model failed or could not be reached. Not charged.

Media typeapplication/json
object
error
required
object
type
string
param

The request field at fault, when there is one (speech).

string | null
code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:
string
message
string

Example 

{
  "error": {
    "type": "billing_error"
  }
}

503

Section titled “503”

overloaded_error: Aderra is busy receiving other large requests. Retry after Retry-After (5) seconds.

Media typeapplication/json
object
type
required
string
Allowed value: error
error
required
object
type
string
Allowed values: invalid_request_error authentication_error permission_error billing_error rate_limit_error request_too_large api_error overloaded_error
message
string

Example 

{
  "type": "error",
  "error": {
    "type": "invalid_request_error"
  }
}

Headers

Section titled “Headers”
Retry-After
integer
Example 
12

Whole seconds to wait before trying again.