API Reference

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.

Open Settings → API Key from the left sidebar in the Push AI dashboard
Click Create Key
Copy the key immediately — it is only shown once

API Key settings page — The API Key page in Settings, found under the Admin section of the sidebar.

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

Field	Description
`code`	Machine-readable error code for programmatic handling.
`message`	Human-readable description.
`request_id`	Unique ID for this request. Include it when contacting support. Also returned in the `X-Request-Id` response header.

Common error codes

Code	Status	Meaning
`missing_api_key`	401	No `x-api-key` header provided.
`invalid_api_key`	401	Key is invalid or has been revoked.
`agent_not_found`	404	Agent doesn’t exist, isn’t published, or belongs to another org.
`run_not_found`	404	Run ID not found or belongs to another org.
`unknown_parameter`	400	Parameter name doesn’t match any defined on the agent.
`invalid_parameter_value`	400	The value provided for a parameter doesn’t match any known option.
`internal_error`	500	Unexpected 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.

Overview

Endpoints

Base URL

Authentication

Creating an API key

Regenerating or revoking a key

Errors

Common error codes

Rate limits

​Base URL

​Authentication

​Creating an API key

​Regenerating or revoking a key

​Errors

​Common error codes

​Rate limits

Base URL

Authentication

Creating an API key

Regenerating or revoking a key

Errors

Common error codes

Rate limits