API Overview
Authenticate and interact with AgentStead programmatically using the REST API and Personal Access Tokens.
The AgentStead API lets you manage agents, secrets, backups, and schedules from scripts, CI pipelines, or any HTTP client. Everything you can do in the dashboard you can do via the API.
Base URL
https://api.agentstead.devAll endpoints are prefixed with /api. Example: https://api.agentstead.dev/api/agents.
Authentication
Two authentication methods are supported:
The recommended method for scripts and automation. Generate a token from Settings → API → New Token and pass it in every request:
Authorization: Bearer x3s_your_token_hereTokens start with x3s_ followed by 24 random characters. They are shown once at creation — copy them immediately.
Personal Access Token scopes
Every PAT is created with one or more scopes. Requests fail with 403 if the token lacks the required scope for the endpoint.
| Scope | What it allows |
|---|---|
read | List and inspect agents, read logs, check health and status |
deploy | Start, stop, restart, and deploy agents |
full | All operations — read, deploy, secrets management, settings, backups |
Create tokens with the minimum scope needed. Use read for monitoring scripts, deploy for CI pipelines, and full only when you need secrets access.
Authentication flow
Error format
All errors return JSON with an error field:
{
"error": "Unauthorized"
}Common status codes:
| Code | Meaning |
|---|---|
200 | OK |
201 | Created |
204 | No content (successful delete) |
400 | Bad request — check your request body |
401 | Not authenticated — missing or invalid token |
403 | Forbidden — token lacks required scope |
404 | Resource not found |
429 | Rate limited — slow down |
500 | Server error |
Rate limits
API requests are rate-limited per account. If you hit 429, back off and retry with exponential backoff.