Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.push.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Push AI API lets you list your published agents, invoke them with parameters, and poll for results — all from your own code, scripts, or backend services.

​
Base URL

https://api.push.ai/api/v1

​
Authentication

All endpoints require an API key passed in the x-api-key header. 
curl https://api.push.ai/api/v1/agents \
  -H "x-api-key: YOUR_API_KEY"
API keys are scoped to your organization. Every key you create can access all published agents in your org.

​
Creating an API key

API key management is only available to Admin users. If you don’t see the API Key option in Settings, contact your organization’s admin.
  1. Open Settings → API Key from the left sidebar in the Push AI dashboard
  2. Click Create Key
  3. Copy the key immediately — it is only shown once
API Key settings page

​
Regenerating or revoking a key

From the same Settings → API Key page, you can:
  • Regenerate — creates a new key and invalidates the old one
  • Revoke — permanently disables the key
Revoked or regenerated keys return 401 immediately. Make sure to update any scripts or integrations using the old key.

​
Errors

All errors return a consistent JSON envelope: 
{
  "error": {
    "code": "agent_not_found",
    "message": "Agent 123 not found or not published.",
    "request_id": "req_abc123"
  }
}
FieldDescription
codeMachine-readable error code for programmatic handling.
messageHuman-readable description.
request_idUnique ID for this request. Include it when contacting support. Also returned in the X-Request-Id response header.

​
Common error codes

CodeStatusMeaning
missing_api_key401No x-api-key header provided.
invalid_api_key401Key is invalid or has been revoked.
agent_not_found404Agent doesn’t exist, isn’t published, or belongs to another org.
run_not_found404Run ID not found or belongs to another org.
unknown_parameter400Parameter name doesn’t match any defined on the agent.
invalid_parameter_value400The value provided for a parameter doesn’t match any known option.
internal_error500Unexpected server error. Retry or contact support with the request_id.

​
Rate limits

Rate limiting is enforced per API key. Current limits are generous for normal usage. If you hit a limit, you’ll receive a 429 response — back off and retry.