Screen Reader Detection Service - API Contract

GET /api/v1/screen-reader-states/api/v1/screen-reader-states

List historical screen reader detection snapshots

Public

Response Example

{
  "data": [
    {
      "id": "sr-state-001",
      "is_active": true,
      "reader_name": "TalkBack",
      "platform": "android",
      "detected_at": "2026-03-26T09:42:00Z"
    },
    {
      "id": "sr-state-002",
      "is_active": false,
      "reader_name": null,
      "platform": "android",
      "detected_at": "2026-03-26T10:01:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

GET /api/v1/screen-reader-states/api/v1/screen-reader-states/:id

Get a specific screen reader state snapshot by ID

Public

Response Example

{
  "id": "sr-state-001",
  "is_active": true,
  "reader_name": "TalkBack",
  "platform": "android",
  "detected_at": "2026-03-26T09:42:00Z"
}

POST /api/v1/screen-reader-states/api/v1/screen-reader-states

Record a screen reader state change event

Public

Request Example

{
  "is_active": true,
  "reader_name": "VoiceOver",
  "platform": "ios"
}

Response Example

{
  "id": "sr-state-003",
  "is_active": true,
  "reader_name": "VoiceOver",
  "platform": "ios",
  "detected_at": "2026-03-26T11:00:00Z"
}

PUT /api/v1/screen-reader-states/api/v1/screen-reader-states/:id

Update metadata on a recorded screen reader state

Public

Request Example

{
  "reader_name": "VoiceOver",
  "platform": "ios"
}

Response Example

{
  "id": "sr-state-003",
  "is_active": true,
  "reader_name": "VoiceOver",
  "platform": "ios",
  "detected_at": "2026-03-26T11:00:00Z",
  "updated_at": "2026-03-26T11:05:00Z"
}

DELETE /api/v1/screen-reader-states/api/v1/screen-reader-states/:id

Delete a screen reader state snapshot record

Public

Response Example

{
  "message": "Screen reader state sr-state-003 deleted successfully"
}

POST /api/v1/screen-reader-states/api/v1/screen-reader-states/refresh

Trigger an immediate refresh of the current screen reader detection state

Public

Request Example

{}

Response Example

{
  "id": "sr-state-004",
  "is_active": true,
  "reader_name": "TalkBack",
  "platform": "android",
  "detected_at": "2026-03-26T11:10:00Z"
}

POST /api/v1/screen-reader-states/api/v1/screen-reader-states/callbacks

Register a webhook callback to be notified on screen reader state changes

Public

Request Example

{
  "callback_url": "https://app.example.com/hooks/screen-reader",
  "event_types": [
    "activated",
    "deactivated"
  ]
}

Response Example

{
  "id": "cb-0017",
  "callback_url": "https://app.example.com/hooks/screen-reader",
  "event_types": [
    "activated",
    "deactivated"
  ],
  "registered_at": "2026-03-26T11:11:00Z"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}