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