Semantics Service Facade - API Contract

GET /api/v1/semantic-announcements/api/v1/semantic-announcements

List recent semantic announcements dispatched to accessibility services

Public

Response Example

{
  "data": [
    {
      "id": "ann-001",
      "message": "Form submitted successfully",
      "text_direction": "ltr",
      "for_accessibility": true,
      "announced_at": "2026-03-26T09:55:00Z"
    },
    {
      "id": "ann-002",
      "message": "3 validation errors found",
      "text_direction": "ltr",
      "for_accessibility": true,
      "announced_at": "2026-03-26T10:02:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

GET /api/v1/semantic-announcements/api/v1/semantic-announcements/:id

Get a specific semantic announcement record

Public

Response Example

{
  "id": "ann-001",
  "message": "Form submitted successfully",
  "text_direction": "ltr",
  "for_accessibility": true,
  "announced_at": "2026-03-26T09:55:00Z"
}

POST /api/v1/semantic-announcements/api/v1/semantic-announcements

Dispatch a semantic announcement to the active screen reader

Public

Request Example

{
  "message": "Your appointment has been confirmed for April 3rd at 2:00 PM",
  "text_direction": "ltr",
  "for_accessibility": true
}

Response Example

{
  "id": "ann-003",
  "message": "Your appointment has been confirmed for April 3rd at 2:00 PM",
  "text_direction": "ltr",
  "for_accessibility": true,
  "semantics_enabled": true,
  "active_reader": "TalkBack",
  "announced_at": "2026-03-26T11:50:00Z"
}

PUT /api/v1/semantic-announcements/api/v1/semantic-announcements/:id

Update the message or direction of a queued announcement before dispatch

Public

Request Example

{
  "message": "Your appointment has been confirmed for April 3rd at 2:30 PM",
  "text_direction": "ltr"
}

Response Example

{
  "id": "ann-003",
  "message": "Your appointment has been confirmed for April 3rd at 2:30 PM",
  "text_direction": "ltr",
  "for_accessibility": true,
  "announced_at": "2026-03-26T11:50:00Z",
  "updated_at": "2026-03-26T11:51:00Z"
}

DELETE /api/v1/semantic-announcements/api/v1/semantic-announcements/:id

Remove an announcement log record

Public

Response Example

{
  "message": "Announcement ann-003 deleted"
}

GET /api/v1/semantic-announcements/api/v1/semantic-announcements/status

Check if semantics service is enabled and which screen reader is active

Public

Response Example

{
  "is_enabled": true,
  "active_reader": "TalkBack",
  "platform": "android",
  "checked_at": "2026-03-26T11:52:00Z"
}

Additional Metadata

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