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

# API Reference

> Programmatic access to Push AI agents

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.

```bash theme={null}
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

<Note>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.</Note>

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

<Frame caption="The API Key page in Settings, found under the Admin section of the sidebar.">
  <img src="https://mintcdn.com/pushai/yPafCVm7KdJYitN4/images/api-key-settings.png?fit=max&auto=format&n=yPafCVm7KdJYitN4&q=85&s=a3fdb683759197792b15fbbf9b1c804e" alt="API Key settings page" width="2860" height="1542" data-path="images/api-key-settings.png" />
</Frame>

### 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:

```json theme={null}
{
  "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.