Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mossdesk.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

https://api.mossdesk.com/api/v1
All endpoints are prefixed with /api/v1.

​
Authentication

Authenticate with an API key using the X-API-Key header: 
curl https://api.mossdesk.com/api/v1/contacts \
  -H "X-API-Key: moss_k_your_api_key_here"
API keys have two scopes:
ScopeAccess
fullRead and write access to all endpoints
read_onlyRead-only access — mutations return 403 Forbidden
Create API keys in the dashboard under Settings > API Keys or via moss key create.

​
Response Envelope

All responses use a consistent JSON envelope.

​
Single resource

{
  "data": {
    "id": "cnt_abc123",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@acme.com"
  }
}

​
List

{
  "data": [
    { "id": "cnt_abc123", "first_name": "Jane" },
    { "id": "cnt_def456", "first_name": "Bob" }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}

​
Deletion

{
  "data": null
}

​
Error Responses

Errors return an appropriate HTTP status code with a structured error body: 
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Contact not found"
  }
}
HTTP StatusError CodeDescription
400VALIDATION_ERRORInvalid request body or parameters
401UNAUTHORIZEDMissing or invalid authentication
403FORBIDDENInsufficient permissions or scope
404NOT_FOUNDResource not found
409CONFLICTDuplicate or conflicting operation
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

​
Pagination

List endpoints accept these query parameters:
ParameterTypeDefaultMaxDescription
pageinteger1—Page number (1-indexed)
per_pageinteger25250Items per page
sortstringvaries—Field to sort by
orderstringdesc—Sort order: asc or desc
Pagination metadata is included in the meta object of list responses.

​
Idempotency

For mutation endpoints (POST, PATCH, DELETE), include the Idempotency-Key header to prevent duplicate operations: 
curl -X POST https://api.mossdesk.com/api/v1/contacts \
  -H "X-API-Key: moss_k_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"first_name": "Jane", "email": "jane@acme.com"}'
If the same idempotency key is sent again, the original response is returned without creating a duplicate.

​
Request Tracing

Include the X-Request-Id header to attach a trace ID to your request. This ID appears in audit logs and can help with debugging. 
curl https://api.mossdesk.com/api/v1/contacts \
  -H "X-API-Key: moss_k_..." \
  -H "X-Request-Id: req-abc-123"