API Reference

AgentState REST API. All endpoints require a Bearer token.

Authentication

Pass your API key as a Bearer token in every request:

Authorization: Bearer <your-api-key>

API Base URL: https://agentstate.app/api

Message Format

{
  "role": "user | assistant | system | tool",
  "content": "message text",
  "metadata": {}        // optional arbitrary JSON
}

Endpoints

POST/api/v1/conversations

Create a new conversation with optional initial messages.

Request body

{
  "title": "optional title",
  "external_id": "your-own-id",
  "messages": [
    { "role": "user", "content": "Hello" }
  ],
  "metadata": {}
}

Response

{
  "id": "conv_01jx...",
  "title": "New Conversation",
  "created_at": "2026-03-15T00:00:00Z"
}

GET/api/v1/conversations

List all conversations for the authenticated project.

Response

{
  "conversations": [...],
  "total": 42
}

GET/api/v1/conversations/:id

Get a conversation and all its messages.

Response

{
  "id": "conv_01jx...",
  "title": "...",
  "messages": [
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." }
  ]
}

GET/api/v1/conversations/by-external-id/:eid

Look up a conversation by your own external identifier.

PUT/api/v1/conversations/:id

Update conversation title or metadata.

Request body

{
  "title": "Updated title",
  "metadata": { "tag": "support" }
}

DELETE/api/v1/conversations/:id

Delete a conversation and all its messages. Irreversible.

POST/api/v1/conversations/:id/messages

Append one or more messages to an existing conversation.

Request body

{
  "messages": [
    { "role": "assistant", "content": "Hello!", "metadata": {} }
  ]
}

POST/api/v1/conversations/:id/generate-title

Use AI to generate a descriptive title based on conversation content.

Response

{ "title": "Generated title" }

POST/api/v1/conversations/:id/follow-ups

Use AI to suggest follow-up questions or actions based on the conversation.

Response

{ "follow_ups": ["...", "..."] }

Machine-readable docs: agents.md →v1