API Overview - MeshAI Documentation

Base URL

All API requests use the following base URL:

https://api.meshai.dev/api/v1

Authentication

Include your API key as a Bearer token in the Authorization header:

curl https://api.meshai.dev/api/v1/agents \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

API keys start with msh_. Create keys in the dashboard at Settings → API Keys. See Authentication for key types, scopes, and signup/login endpoints.

Response Format

All responses use a consistent envelope:

Success

{
  "success": true,
  "data": { ... }
}

Success (Paginated)

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20
  }
}

Error

{
  "success": false,
  "error": "Human-readable error message",
  "code": "VALIDATION_ERROR"
}

Common Error Codes

HTTP Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request body or parameters
401	`UNAUTHORIZED`	Missing or invalid API key
402	`PLAN_LIMIT_REACHED`	Agent limit or feature not available on your plan
403	`FORBIDDEN`	Insufficient permissions or policy violation
404	`NOT_FOUND`	Resource not found
409	`CONFLICT`	Resource already exists (e.g., duplicate agent name)
429	`RATE_LIMITED`	Too many requests: retry after the `Retry-After` header value
500	`INTERNAL_ERROR`	Server error: contact support

Pagination

List endpoints support pagination with page and limit query parameters:

curl "https://api.meshai.dev/api/v1/agents?page=2&limit=50" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-based)
`limit`	integer	20	Results per page (max 100)

The response meta object contains the total count for building pagination UI.

Rate Limits

Plan	Requests/min
Starter	60
Professional	300
Enterprise	1,000
Enterprise Plus	Custom

Rate-limited responses include a Retry-After header (seconds).

Content Type

All POST/PATCH/PUT requests must include:

Content-Type: application/json

​Base URL

​Authentication

​Response Format

​Success

​Success (Paginated)

​Error

​Common Error Codes

​Pagination

​Rate Limits

​Content Type