Graine AI
API referenceAgents

Archive an agent

Archive an agent.

Archive an agent.

This is a soft delete. The agent's status becomes ARCHIVED and it disappears from the default listing, but the record and its call history are retained. There is no hard-delete on this API.

An ACTIVE agent cannot be archived — set its status to INACTIVE first, or this returns 409 (code 1201).

Rate limit: 1000 requests per minute per organization (bucket default). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

DELETE
/v2/agents/{agent_id}
/v2/agents/6c6f4cc3-f56c-479d-8422-7f76694daa29

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Path Parameters

agent_id
Required
Agent Id

Agent identifier.

Query Parameters

organization_idOrganization Id

Must match the organisation the API key belongs to.

Response Body

200

Confirmation that the agent is archived.

agent_id
Required
Agent Id

The agent that was archived.

statusStatus

Always ARCHIVED — this is a soft delete.

Default: "ARCHIVED"

deletedDeleted

True once the agent has been archived.

Default: true

400

1000 — malformed or contradictory input. 1002 — a required parameter is missing.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented instead of an API key.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organization. GET /v2/scopes reports what a key holds.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

404

1200 — no such resource in your organization. A resource belonging to another organization answers 404, never 403.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

409

1201 — the resource's current state does not allow this action.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

422

1001 — the body or query failed validation; the message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — the per-organization request rate or concurrent-call limit was reached. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

503

1501 — a service this endpoint depends on is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

504

1502 — a service this endpoint depends on did not answer in time.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

curl -X DELETE "https://api.graine.ai/v2/agents/6c6f4cc3-f56c-479d-8422-7f76694daa29?organization_id=string" \
  -H "Authorization: Bearer <token>"

Confirmation that the agent is archived.

{
  "agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29",
  "status": "ARCHIVED",
  "deleted": true
}

Previous

Update an agent PATCH

Next

Get an A/B experiment GET