API Reference

Complete REST API documentation. Base URL: https://agenthistory.ai

Records API

Manage agent records (memory containers).

Create Record

Free

POST /api/v1/records
Content-Type: application/json
Authorization: Bearer <agentKey>

{
  "name": "MyAgent",
  "tags": ["assistant", "coding"],
  "category": "personal"
}

Response:

{
  "success": true,
  "data": {
    "id": "rec_01jx8a7qz2...",
    "name": "MyAgent",
    "tags": ["assistant", "coding"],
    "category": "personal",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Request Body

Field	Type	Required	Description
`name`	string	Yes	Record name (1-128 chars)
`tags`	string[]	No	Tags for categorization (max 10)
`category`	string	No	Category (max 32 chars, default: "general")
`parentRecordId`	string	No	Parent record for hierarchies

List Records

Free

GET /api/v1/records?limit=20&offset=0
Authorization: Bearer <agentKey>

Get Record

Free

GET /api/v1/records/{recordId}
Authorization: Bearer <agentKey>

Update Record

Free

PATCH /api/v1/records/{recordId}
Content-Type: application/json
Authorization: Bearer <agentKey>

{
  "name": "UpdatedName",
  "tags": ["new-tag"]
}

Delete Record

Free

DELETE /api/v1/records/{recordId}
Authorization: Bearer <agentKey>

Memory API

Store, search, and retrieve memories.

Recall (Semantic Search)

$0.05/query

POST /api/v1/records/{recordId}/recall
Content-Type: application/json
Authorization: Bearer <agentKey>

{
  "query": "user preferences for morning meetings",
  "limit": 10,
  "types": ["fact", "relationship"]
}

Response:

{
  "success": true,
  "data": {
    "memories": [
      {
        "id": "mem_...",
        "path": "relationships/john-smith",
        "type": "relationship",
        "summary": "John Smith prefers morning appointments",
        "similarity": 0.92
      }
    ],
    "count": 1
  }
}

Request Body

Field	Type	Required	Description
`query`	string	Yes	Search query (1-1000 chars)
`limit`	number	No	Max results (1-50, default: 10)
`types`	string[]	No	Filter by memory types

Remember (Store Memory)

$0.05/write

POST /api/v1/records/{recordId}/remember
Content-Type: application/json
Authorization: Bearer <agentKey>

{
  "content": "John Smith prefers morning appointments before 10am",
  "type": "relationship",
  "path": "relationships/john-smith"
}

Response:

{
  "success": true,
  "data": {
    "id": "mem_...",
    "path": "relationships/john-smith",
    "type": "relationship",
    "summary": "John Smith prefers morning appointments"
  }
}

Request Body

Field	Type	Required	Description
`content`	string	Yes	Memory content (1-50KB)
`type`	string	No	Memory type (auto-classified if omitted)
`path`	string	No	Storage path (max 256 chars)
`idempotency_key`	string	No	Prevent duplicate writes

Read File

$0.05/file

GET /api/v1/records/{recordId}/read?path=config/settings
Authorization: Bearer <agentKey>

Response:

{
  "success": true,
  "data": {
    "content": "{ \"theme\": \"dark\", \"language\": \"en\" }",
    "path": "config/settings"
  }
}

Write File

$0.05/file

POST /api/v1/records/{recordId}/write
Content-Type: application/json
Authorization: Bearer <agentKey>

{
  "path": "config/settings",
  "content": "{ \"theme\": \"dark\", \"language\": \"en\" }"
}

Response:

{
  "success": true,
  "data": {
    "path": "config/settings",
    "contentHash": "abc123..."
  }
}

Request Body

Field	Type	Required	Description
`path`	string	Yes	File path (max 256 chars)
`content`	string	Yes	File content (max 1MB)
`idempotency_key`	string	No	Prevent duplicate writes

Get Full Context

$0.05/request

GET /api/v1/records/{recordId}/context
Authorization: Bearer <agentKey>

Response:

{
  "success": true,
  "data": {
    "identity": [...],
    "fact": [...],
    "relationship": [...],
    "episode": [...],
    "skill": [...]
  }
}

Raw Blob Access (LOCAL Mode)

Free

POST /api/v1/records/{recordId}/raw
GET /api/v1/records/{recordId}/raw
Authorization: Signature <sig>

Direct blob storage for LOCAL mode with wallet signature authentication.

Agent API

Create and manage agents.

Create Agent

Free

POST /api/v1/agents
Content-Type: application/json

{
  "name": "MyAgent",
  "mode": "cloud"
}

Response:

{
  "success": true,
  "data": {
    "agentKey": "aht_live_...",
    "recordId": "rec_...",
    "walletAddress": "0x...",
    "mode": "cloud"
  }
}

Request Body

Field	Type	Required	Description
`name`	string	Yes	Agent name (1-128 chars)
`mode`	string	No	"local" or "cloud" (default: "cloud")
`tags`	string[]	No	Tags for categorization
`category`	string	No	Agent category (default: "agent")

Get Agent

Free

GET /api/v1/agents
Authorization: Bearer <agentKey>

Error Responses

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Content is required"
  }
}

Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request body
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`RATE_LIMITED`	429	Too many requests
`PAYMENT_REQUIRED`	402	Insufficient payment
`INTERNAL_ERROR`	500	Server error

Rate Limits

Endpoint	Limit
All endpoints	100 requests/minute per agent
Remember/Write	30 writes/minute per record
Recall/Context	60 queries/minute per record

See Pricing for operation costs or Authentication for auth details.