Dialcues | Never Miss a Moment

Introduction

The Dialcues API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Dialcues API in test mode by generating a key from Settings → API. Test and production keys both use the dc_live_ prefix.

# Base URL
https://api.yourapp.com/api/public/v1

# All requests require a Bearer token
curl https://api.yourapp.com/api/public/v1/me \
  -H "Authorization: Bearer dc_live_xxx"

Authentication

The Dialcues API uses API keys to authenticate requests. You can view and manage your API keys in Settings → API.

Your API keys carry many privileges; keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must include Authorization: Bearer <key>. Requests without authentication will fail with 401.

Your API key

A test API key is included in all examples. Replace the sample key with your actual API key to test requests against your account.

curl https://api.yourapp.com/api/public/v1/reminders \
  -H "Authorization: Bearer dc_live_xxxxxxxxxxxxxxxx"
  # The bearer token authenticates every request.

Errors

Dialcues uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the 2xx range indicate success, codes in the 4xx range indicate a client error, and codes in the 5xx range indicate a server error.

Code	Status	Meaning
200	OK	Everything worked as expected.
201	Created	A new resource was successfully created.
400	Bad Request	The request was unacceptable, often due to a missing required parameter.
401	Unauthorized	No valid API key provided.
404	Not Found	The requested resource doesn't exist.
500	Server Error	Something went wrong on our end.

Error codes & messages

For public API endpoints, errors always return the same shape:{ error: { code, message, details } }. The message is human-friendly; the code is stable for programmatic handling.

# Error response shape
{
  "error": {
    "code": "validation_error",
    "message": "Scheduled time must be in the future.",
    "details": null
  }
}

# Common error codes:
#  unauthorized         - missing Bearer token
#  invalid_api_key      - key not found
#  api_key_revoked      - key was revoked
#  api_key_expired      - key has expired
#  validation_error     - request body validation failed
#  not_found            - resource does not exist
#  invalid_state        - reminder is not in an editable state
#  internal_error       - unexpected server error (retry OK)

Error codes & messages

This section lists the main error codes you’ll see from /api/public/v1. Use these codes for branching logic and user-facing messages.

Code	Typical HTTP	When it happens
unauthorized	401	Missing `Authorization: Bearer ...`
invalid_api_key	401	Key not found / wrong key
api_key_revoked	401	Key was revoked in Settings → API
api_key_expired	401	Key reached its expiry time
validation_error	400	Missing required fields, invalid phone/timezone/date
missing_outbound_line	400	No Vapi outbound line configured for calling
invalid_state	400	Trying to update a reminder that can’t be edited
not_found	404	Reminder/execution doesn’t exist for this user
internal_error	500	Unexpected error; retry with backoff

# Example: invalid key
HTTP/1.1 401
{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid.",
    "details": null
  }
}

# Example: missing outbound line
HTTP/1.1 400
{
  "error": {
    "code": "missing_outbound_line",
    "message": "Add a Vapi integration with at least one phone number before creating reminders.",
    "details": null
  }
}

Pagination

List endpoints return a paginated response with items, total, page, page_size, and total_pages. Use page and page_size query params to paginate.

curl "https://api.yourapp.com/api/public/v1/reminders?page=2&page_size=20" \
  -H "Authorization: Bearer dc_live_xxxxxxxxxxxxxxxx"

# Response
{
  "items": [/* ... */],
  "total": 93,
  "page": 2,
  "page_size": 20,
  "total_pages": 5
}

Versioning

The public API is versioned in the URL path. Current version is /api/public/v1. When we introduce breaking changes, we’ll ship a new version (e.g. /v2) rather than changing existing behavior.

# v1 base
https://api.yourapp.com/api/public/v1

Identity

GET /api/public/v1/me

Returns the authenticated user identity, organization id, and the API key id associated with the current Bearer token. Useful for verifying credentials programmatically.

Field	Type
user.id	string
user.email	string
user.name	string
organization_id	string
api_key_id	string

curl https://api.yourapp.com/api/public/v1/me \
  -H "Authorization: Bearer dc_live_xxxxxxxxxxxxxxxx"

# Response
{
  "user": {
    "id": "clx...",
    "email": "dev@example.com",
    "name": "Jane"
  },
  "organization_id": "clx...",
  "api_key_id": "clx..."
}

List reminders

GET /api/public/v1/reminders

Returns a paginated list of reminders for the authenticated user. Supports filtering by status, text search, date range, and sort order.

Parameter	Type	Description
status	string	scheduled, paused, completed, failed, in_progress
search	string	Text search on title and message
sort	string	scheduled_at_asc, scheduled_at_desc, updated_at_desc
page	integer	Default 1
page_size	integer	Default 20, max 100

curl "https://api.yourapp.com/api/public/v1/reminders?status=scheduled&page_size=5" \
  -H "Authorization: Bearer dc_live_xxxxxxxxxxxxxxxx"

# Response
{
  "items": [
    {
      "id": 42,
      "title": "Take medication",
      "message": "Time for your pills",
      "phone_number": "+14155552671",
      "scheduled_at": "2026-03-25T13:00:00Z",
      "timezone": "America/New_York",
      "status": "scheduled",
      ...
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 5,
  "total_pages": 1
}

Create reminder

POST /api/public/v1/reminders

Creates a new reminder that will trigger a phone call at the scheduled time.

Field	Required	Description
title	Yes	Short reminder title (max 255 chars)
message	Yes	Message spoken during the call (max 1000 chars)
phone_number	Yes	E.164 format, e.g. +14155552671
scheduled_at	Yes	Local datetime string (future)
timezone	Yes	IANA timezone, e.g. America/New_York
recurrence_type	No	daily, weekly, or custom
recurrence_config	No	{interval_days:N} or {weekdays:[0-6]}

curl -X POST "https://api.yourapp.com/api/public/v1/reminders" \
  -H "Authorization: Bearer dc_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Take medication",
    "message": "Please take your medication now.",
    "phone_number": "+14155552671",
    "scheduled_at": "2026-03-25T09:00:00",
    "timezone": "America/New_York",
    "recurrence_type": "daily"
  }'

# → 201 Created

Retrieve reminder

GET /api/public/v1/reminders/:id

Retrieves a single reminder by its integer id.

curl https://api.yourapp.com/api/public/v1/reminders/42 \
  -H "Authorization: Bearer dc_live_xxxxxxxxxxxxxxxx"

# → 200 OK  (full reminder object)

Update reminder

PATCH /api/public/v1/reminders/:id

Updates a reminder that is in scheduled, paused, or failed state. Send only the fields you want to change. Supports rescheduling, content edits, pause/resume, and recurrence changes.

curl -X PATCH "https://api.yourapp.com/api/public/v1/reminders/42" \
  -H "Authorization: Bearer dc_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title", "scheduled_at": "2026-03-26T10:00:00"}'

# → 200 OK  (updated reminder object)

Delete reminder

DELETE /api/public/v1/reminders/:id

Permanently deletes a reminder by its id. Returns 204 No Content.

curl -X DELETE "https://api.yourapp.com/api/public/v1/reminders/42" \
  -H "Authorization: Bearer dc_live_xxxxxxxxxxxxxxxx"

# → 204 No Content

List executions

GET /api/public/v1/executions

Returns a paginated list of call execution records. Each execution represents a single outbound call attempt.

Parameter	Type	Description
date_from	string	ISO datetime lower bound
date_to	string	ISO datetime upper bound
page	integer	Default 1
page_size	integer	Default 20, max 100

curl "https://api.yourapp.com/api/public/v1/executions?page_size=5" \
  -H "Authorization: Bearer dc_live_xxxxxxxxxxxxxxxx"

# Response
{
  "items": [
    {
      "id": 101,
      "reminder_id": 42,
      "reminder_title": "Take medication",
      "status": "completed",
      "call_id": "abc-123",
      "executed_at": "2026-03-25T13:00:12Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 5,
  "total_pages": 1
}

Canonical docs: docs/public-api.md and docs/public-api.openapi.yaml.