front-api

Front API Skill

Reference for Front REST API integration.

OpenAPI Spec

The full OpenAPI spec is in core-api.json (13k+ lines). Use it as the source of truth for:

• Request/response schemas
• Nullable fields
• Enum values
• Endpoint paths

Key Schemas

Message

• recipients[].name - nullable
• recipients[]._links.related.contact - nullable
• recipients[].role - enum: from, to, cc, bcc, reply-to
• author - nullable (null for inbound from external)
• text - nullable (plain text version of body)

Conversation

• assignee - nullable
• recipient - nullable for some conversation types
• tags - can be empty array
• last_message - nullable
• scheduled_reminders - nullable

Recipient

{
  "name": "string | null",
  "handle": "string (required)",
  "role": "from | to | cc | bcc | reply-to",
  "_links": {
    "related": {
      "contact": "string | null"
    }
  }
}

Common Gotchas

1. Webhooks send previews only - must fetch full data via API
2. Many fields nullable - don't assume presence, use .nullable() in Zod
3. _links.related.contact - null when recipient has no contact record
4. role includes reply-to - often forgotten in enums

SDK Location

@skillrecordings/front-sdk - Zod schemas should match this spec exactly.

Useful Endpoints

• GET /messages/{id} - Full message with body
• GET /conversations/{id} - Conversation details
• GET /conversations/{id}/messages - Message history
• POST /conversations/{id}/drafts - Create draft reply
• GET /inboxes/{id} - Inbox details