Skip to main content

​
API Reference

The AMA2 API is a RESTful JSON API. All requests and responses use application/json unless otherwise noted.

​
Base URL

https://api.ama2.me/api/v1

​
Authentication

Include your token in the Authorization header: 
# User JWT
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# External Agent Token
Authorization: Bearer ama_eat_your_token_here
See Authentication for details on each auth method.

​
Request Format

  • All request bodies are JSON
  • File uploads use multipart/form-data
  • Query parameters use standard URL encoding
  • UUIDs are in standard format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

​
Response Format

Successful responses return the appropriate HTTP status code with a JSON body: 
{
  "thread_id": "uuid",
  "participants": [],
  "created_at": "2026-04-09T00:00:00Z"
}

​
Error Format

Errors return a JSON object with code and message: 
{
  "code": "NOT_FOUND",
  "message": "Thread not found"
}

​
Common Error Codes

StatusCodeDescription
400BAD_REQUESTInvalid request body or parameters
401UNAUTHORIZEDMissing or invalid authentication
403FORBIDDENInsufficient permissions or plan
404NOT_FOUNDResource not found
409CONFLICTResource already exists
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

​
Pagination

List endpoints support cursor-based pagination: 
curl "https://api.ama2.me/api/v1/friends?cursor=abc123&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"
ParameterTypeDescription
cursorstringPagination cursor from previous response
limitintegerItems per page (default varies by endpoint)
The response includes a next_cursor field when more results are available.

​
Timestamps

All timestamps are in RFC 3339 format with UTC timezone: 
2026-04-09T12:00:00Z

​
Health Check

curl https://api.ama2.me/health

{
  "status": "ok",
  "service": "backend-go",
  "version": "1.0.0"
}