Services API

The Services API manages registered service namespaces that own sync documents. Services provide formal identifiers for grouping related documents instead of ad-hoc string names.

All endpoints are scoped by the X-Application-Id header.

List Services

GET /api/services

Response: 200 OK

{
  "services": [
    {
      "id": "a1b2c3d4-...",
      "name": "session",
      "description": "Session state documents",
      "applicationId": "app_abc123",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    }
  ]
}

Get Service

GET /api/services/:id

Response: 200 OK

{
  "id": "a1b2c3d4-...",
  "name": "session",
  "description": "Session state documents",
  "applicationId": "app_abc123",
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}

Create Service

POST /api/services

Request Body:

{
  "name": "session",
  "description": "Session state documents"
}

Field	Type	Required	Description
`name`	`string`	Yes	Unique service name. Must match `^[a-z][a-z0-9_-]*$`.
`description`	`string`	No	Human-readable description.

Response: 201 Created

{
  "id": "a1b2c3d4-...",
  "name": "session",
  "description": "Session state documents",
  "applicationId": "app_abc123",
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}

Update Service

PATCH /api/services/:id

Request Body:

{
  "name": "session-v2",
  "description": "Updated description"
}

Both fields are optional — only included fields are updated.

Response: 200 OK — returns the updated service object.

Delete Service

DELETE /api/services/:id

Response: 204 No Content

Error Responses

Status	Meaning
`400`	Validation error — invalid name format
`404`	Service not found
`409`	Conflict — a service with that name already exists in this application

Service Name Rules

Service names must:

Start with a lowercase letter
Contain only lowercase letters, digits, hyphens, and underscores
Be unique per application

Valid examples: session, order-tracking, chat_rooms

Invalid examples: Session, 123abc, my service