Developer documentation

Base URLs

Quickstart

Create an API key in Dashboard → API & MCP (it's shown once — store it as $KEY), then:

# 1. Grab your profile — sanity-checks the key
curl -H "Authorization: Bearer $KEY" http://portal.dialoguecx.ai/api/v1/me

# 2. Find open slots for an event type
curl -H "Authorization: Bearer $KEY" \
  "http://portal.dialoguecx.ai/api/v1/availability?event_type=intro-call&start=2026-07-10&end=2026-07-14"

# 3. Book one of them (idempotently)
curl -X POST http://portal.dialoguecx.ai/api/v1/bookings \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "event_type": "intro-call",
    "start_time": "2026-07-10T10:00:00-04:00",
    "invitee_name": "Ada Lovelace",
    "invitee_email": "ada@example.com"
  }'

API keys

Keys look like sk_live_… (or sk_test_…), are scoped at creation, revocable, and stored server-side only as a peppered HMAC-SHA256 hash — the full key is shown exactly once. Best for server-to-server integrations and MCP clients you control.

OAuth 2.0 client credentials

For platforms that prefer short-lived tokens, exchange a client id/secret for a one-hour access token (RFC 6749 §4.4). The optional scope parameter requests a subset of the client's granted scopes — tokens never exceed what the credential was granted, even if grants are later reduced.

curl -X POST http://portal.dialoguecx.ai/api/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET \
  -d "scope=availability:read bookings:read bookings:write"

# → { "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600,
#     "scope": "availability:read bookings:read bookings:write" }

Scopes

Every operation requires a scope; a missing scope yields 403 with type …/errors/forbidden listing required_scope and granted_scopes.

Timestamps & timezones

All instants are RFC 3339 / ISO 8601 with an explicit UTC offset, e.g. 2026-07-10T14:00:00-04:00, rendered in the resource's IANA timezone. Storage is UTC; DST math is done per calendar date in the tenant's zone, so a "9:00–17:00" rule stays 9:00–17:00 wall-clock across transitions. Where a bare date is accepted (availability start/end), it is interpreted in the request's timezone, inclusive on the end date.

Errors (RFC 7807)

Every error is an application/problem+json document with a stable type URI you can branch on — never match on human-readable text. Conflict responses carry extensions that make retries possible without a human:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "http://portal.dialoguecx.ai/errors/slot-conflict",
  "title": "Requested time is not available",
  "status": 409,
  "detail": "That slot was booked a moment ago.",
  "instance": "/api/v1/bookings",
  "conflicting_bookings": [
    { "id": "bk_123", "start_time": "2026-07-10T10:00:00-04:00",
      "end_time": "2026-07-10T10:30:00-04:00" }
  ],
  "alternative_slots": [
    { "start": "2026-07-10T10:30:00-04:00", "end": "2026-07-10T11:00:00-04:00" },
    { "start": "2026-07-10T11:00:00-04:00", "end": "2026-07-10T11:30:00-04:00" }
  ]
}

Pagination

List endpoints are cursor-paginated: pass limit (1–100, default 20) and the cursor from the previous page's next_cursor. A null next_cursor means you've reached the end. Cursors are opaque — don't construct them.

curl -H "Authorization: Bearer $KEY" \
  "http://portal.dialoguecx.ai/api/v1/bookings?limit=50&status=confirmed"
# → { "data": [ … ], "next_cursor": "bk_0a1b2c" }

curl -H "Authorization: Bearer $KEY" \
  "http://portal.dialoguecx.ai/api/v1/bookings?limit=50&status=confirmed&cursor=bk_0a1b2c"
# → { "data": [ … ], "next_cursor": null }   // null ⇒ last page

Idempotency

Every mutating endpoint accepts an Idempotency-Key header (any unique string ≤ 255 chars; UUIDv4 recommended). Retrying with the same key and body replays the original response (marked Idempotency-Replayed: true); the same key with a different body returns 409 idempotency-conflict. Always send one when creating bookings from a queue or an agent — a timeout plus a retry must not double-book your invitee.

Rate limits

Limits are enforced per credential. On 429 you get a Retry-After header (seconds) and a rate-limited problem document — back off and retry after that interval.

Endpoint reference

All paths are relative to http://portal.dialoguecx.ai/api/v1.

Reading availability

GET /availability returns real bookable slots: weekly rules and date overrides, minus existing bookings, buffers, and the event type's minimum notice. Never compute slots yourself — a slot the endpoint returns is one POST /bookings will accept (barring a race, which is handled below).

curl -H "Authorization: Bearer $KEY" \
  "http://portal.dialoguecx.ai/api/v1/availability?event_type=intro-call&start=2026-07-10&end=2026-07-12&timezone=America/Toronto"

{
  "event_type_id": "et_8f7d…",
  "timezone": "America/Toronto",
  "slots": [
    { "start": "2026-07-10T09:00:00-04:00", "end": "2026-07-10T09:30:00-04:00" },
    { "start": "2026-07-10T09:30:00-04:00", "end": "2026-07-10T10:00:00-04:00" },
    …
  ]
}

Booking lifecycle

Bookings move through three states: confirmed → cancelled (soft, keeps the record) or rescheduled (the original points to its replacement via rescheduled_from_id). Double-booking is impossible even under concurrent writers — a database exclusion constraint guarantees it — so a lost race surfaces as a clean 409 slot-conflict with alternative_slots you can offer instead.

# Reschedule: old booking → status "rescheduled", replacement returned
curl -X POST http://portal.dialoguecx.ai/api/v1/bookings/bk_123/reschedule \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "start_time": "2026-07-11T14:00:00-04:00" }'

# Cancel: soft state change, record stays readable
curl -X DELETE "http://portal.dialoguecx.ai/api/v1/bookings/bk_123?reason=Client%20asked" \
  -H "Authorization: Bearer $KEY"

Tools

Tool errors return the same RFC 7807 documents as REST, as structured tool results — so an agent hitting a slot conflict sees alternative_slots and can offer the invitee a new time, and an ambiguous cancel request gets a matches list to ask the human about. Give agent credentials only the scopes they need — a read-only assistant works fine with just event-types:read + availability:read + bookings:read.

Connect from Claude Code

claude mcp add --transport http schedulercx http://portal.dialoguecx.ai/api/mcp \
  --header "Authorization: Bearer sk_live_your_key_here"

# then, inside Claude Code:
#   > find a 30-minute slot next Tuesday afternoon and book it
#   > for jane@acme.com — she wants to discuss the Q3 rollout

Connect from Claude Desktop / claude.ai

Add a custom connector (Settings → Connectors → Add custom connector) pointing at http://portal.dialoguecx.ai/api/mcp, or use an mcp.json-style config where your client supports HTTP servers with headers:

{
  "mcpServers": {
    "schedulercx": {
      "type": "http",
      "url": "http://portal.dialoguecx.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_key_here"
      }
    }
  }
}

Other clients (stdio-only)

Clients that only speak stdio can bridge through mcp-remote:

{
  "mcpServers": {
    "schedulercx": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://portal.dialoguecx.ai/api/mcp",
        "--header", "Authorization: Bearer sk_live_your_key_here"
      ]
    }
  }
}

Your personal MCP URL also appears in GET /me as mcp_url, and in Dashboard → API & MCP.