REST API¶

Base URL: https://agntapi.agntspark.com/v1

Authenticate with Authorization: Bearer <token>, where the token is an API key (agnt_…) or a console session token. Request and response bodies are JSON.

Errors¶

{"code": "QUOTA_EXCEEDED", "message": "The free plan allows 3 running replicas; this would use 4.", "details": {…}}

Status	Typical `code`
`401`	`AUTHENTICATION_FAILED`: missing, invalid or expired token
`403`	`AUTHORISATION_DENIED` (your role can't do this), `QUOTA_EXCEEDED`, `INVALID_INVITE`
`404`	`NOT_FOUND`: doesn't exist, or isn't yours
`409`	`EMAIL_ALREADY_REGISTERED`, `ALREADY_SUBSCRIBED`, `NO_BILLING_ACCOUNT`
`422`	`VALIDATION_ERROR`, with `details.errors[]` of `{loc, msg, type}`
`429`	`RATE_LIMIT_EXCEEDED`, with a `Retry-After` header
`501`	`BUILD_NOT_SUPPORTED`
`502`	`DEPLOYMENT_FAILED`: the container couldn't be started
`503`	`BILLING_NOT_CONFIGURED`

Agents¶

The agent object¶

{
  "id": "agt_…",
  "name": "support",
  "runtime": "python3.12",
  "framework": "custom",
  "model": "gpt-4o",
  "status": "running",
  "url": "https://support-k3v9qa.run.agntspark.com",
  "access": "private",
  "rate_limit_rpm": null,
  "access_key": null,
  "replicas": 1,
  "deploy": {
    "image": "agntspark/template-customer-support:latest",
    "replicas": 1,
    "resources": {"cpu": 1.0, "memory_mb": 512, "gpu": 0, "disk_gb": 10, "ephemeral_storage_gb": 5},
    "env": [{"key": "OPENAI_API_KEY", "value": "***", "secret": true}],
    "port": 8080,
    "auto_scale": false,
    "min_replicas": 1,
    "max_replicas": 10
  },
  "tags": [],
  "metadata": {},
  "error": null,
  "version": 2,
  "created_at": "2026-09-15T08:00:00Z",
  "updated_at": "2026-09-15T08:00:05Z"
}

status is one of pending, starting, running, scaling, stopped, failed, crashed. Secret environment values are always returned as ***.

`POST /agents`¶

Create an agent, and deploy it if deploy is given.

Field	Type	Default
`name`	string	—	Required, 1–128 characters.
`model`	string	`gpt-4o`	Also selects the provider.
`api_key`	string	—	Your model provider key; stored encrypted.
`system_prompt`	string	—	Up to 32,000 characters. Replaces a template's prompt.
`access`	`public` \| `private`	`private`
`deploy`	object	—	See below.
`tags`	string[]	`[]`
`metadata`	object	`{}`	String values.

deploy:

Field	Type	Default
`image`	string	platform runtime	Public image to run.
`port`	int	`8080`	Port your container listens on.
`replicas`	int	`1`
`resources.cpu`	number	`1.0`	vCPUs per replica.
`resources.memory_mb`	int	`512`	Memory per replica.
`env`	`{key, value, secret}`[]	`[]`
`auto_scale`	bool	`false`
`min_replicas` / `max_replicas`	int	`1` / `10`

Returns 201 with the agent. For a private agent, access_key holds its first access key (label default). It isn't returned anywhere else, so store it; in every other response access_key is null.

`GET /agents`¶

Your agents, newest first. Query: status, tag, page (from 1), page_size (1–100, default 20).

{"agents": [ … ], "total": 3, "page": 1, "page_size": 20, "has_next": false}

`GET /agents/{id}`¶

One agent.

`PATCH /agents/{id}`¶

Change access settings. Omitted fields stay as they are.

{"access": "private", "rate_limit_rpm": 30}

rate_limit_rpm is 1–100,000, or null for the default (120).

`POST /agents/{id}/deploy`¶

Redeploy, optionally with a new deploy object as the body. The model key is kept unless the new env sets it.

`POST /agents/{id}/scale`¶

{"direction": "up", "count": 1}

Returns {"agent_id", "previous_replicas", "current_replicas", "direction", "status"}.

`DELETE /agents/{id}`¶

Stops the agent's containers and deletes it, with its access keys. Returns 204.

`GET /agents/{id}/logs`¶

Recent container output. Query: limit (1–1000, default 100), level, replica_id.

{"logs": [{"agent_id", "replica_id", "timestamp", "level", "message", "source": "stdout"}], "total": 42}

GET /agents/{id}/logs/stream streams the same as server-sent events.

`GET /agents/{id}/metrics`¶

Live CPU and memory, averaged across replicas:

{"agent_id": "agt_…", "timestamp": "…", "cpu_percent": 3.2, "memory_mb": 88, "memory_percent": 17.2, "replicas": 1}

Request and latency fields are present but always 0 for now; request counts are in usage. GET /agents/{id}/metrics/stream?interval=10 streams them.

Access keys¶

`POST /agents/{id}/access-keys`¶

{"label": "website"}

Returns 201:

{"id": "…", "label": "website", "key_preview": "agk_Xy12abcd...", "created_at": "…", "key": "agk_…"}

key is only returned here.

`GET /agents/{id}/access-keys`¶

The agent's keys, without key.

`DELETE /agents/{id}/access-keys/{key_id}`¶

Revokes the key immediately. Returns 204.

Account¶

`GET /account/usage`¶

{
  "plan": "free",
  "exempt": false,
  "limits": {
    "max_agents": 3, "max_replicas": 3, "max_vcpu": 3.0, "max_memory_mb": 1536,
    "max_replica_cpu": 1.0, "max_replica_memory_mb": 1024, "max_agent_rpm": 300
  },
  "usage": {"agents": 2, "replicas": 2, "vcpu": 1.5, "memory_mb": 1024},
  "period": {
    "start": "2026-09-01T00:00:00Z",
    "replica_hours": 310.5, "vcpu_hours": 155.2, "memory_gb_hours": 155.2,
    "requests": 18234
  }
}

usage is what's running now; period is metered since the first of the month (UTC).

API keys¶

These need a console session token, not an API key.

Endpoint
`POST /api-keys` `{"label"}`	Create; the raw key is only in this response.
`GET /api-keys`	List your keys.
`DELETE /api-keys/{id}`	Revoke.

Auth¶

Endpoint
`GET /auth/registration`	`{"mode": "open" \\| "invite" \\| "closed"}`
`POST /auth/register` `{"email", "password", "name", "invite_code"}`	Create an account; returns a session token.
`POST /auth/login` `{"email", "password"}`	Returns a session token, valid for 60 minutes.
`GET /auth/me`	The signed-in user.

REST API¶

Errors¶

Agents¶

The agent object¶

POST /agents¶

GET /agents¶

GET /agents/{id}¶

PATCH /agents/{id}¶

POST /agents/{id}/deploy¶

POST /agents/{id}/scale¶

DELETE /agents/{id}¶

GET /agents/{id}/logs¶

GET /agents/{id}/metrics¶