List Appointments

GET

/public/v1/appointments

curl --request GET \
  --url 'https://api.aymaragents.com/public/v1/appointments?offset=0&limit=50' \
  --header 'X-API-Key: <X-API-Key>'

• Producción

List the tenant’s appointments, filterable by userId/customerId/leadId/ status/from/to (SPEC_API_PUBLICA.md §2.4) – an unknown/foreign filter value simply matches nothing, never 404 (listing filter, same convention as customerId on GET /public/v1/leads).

---

Permiso necesario: tenant:appointments.read

Authorizations

• ApiKeyAuth

Parameters

Query Parameters

userId

Any of:

string

string format: uuid

null

null

customerId

Any of:

string

string format: uuid

null

null

leadId

Any of:

string

string format: uuid

null

null

status

Any of:

string

string

null

null

from

Any of:

string

string format: date-time

null

null

to

Any of:

string

string format: date-time

null

null

offset

Offset

integer

0

limit

Limit

integer

default: 50 >= 1 <= 200

Responses

200

Successful Response

Media typeapplication/json

PublicAppointmentsResponse

GET /public/v1/appointments response envelope.

object

items

required

Items

Array<object>

PublicAppointmentOut

A single appointment, curated subset of the internal AppointmentOut.

Drops googleEventId (CAL-11 internal Google Calendar mirror id, meaningless to a third party) and createdBy (the internal actor id – Platform-only attribution; a public caller already knows who acted, it was its own key).

object

id

required

Id

string

assignedUserId

required

Assigneduserid

string

customerId

Any of:

string

string

null

null

conversationId

Any of:

string

string

null

null

leadId

Any of:

string

string

null

null

title

required

Title

string

appointmentType

required

Appointmenttype

string

startsAt

required

Startsat

string

endsAt

required

Endsat

string

status

required

Status

string

source

required

Source

string

notes

Any of:

string

string

null

null

createdAt

required

Createdat

string

updatedAt

required

Updatedat

string

total

required

Total

integer

pagination

required

OffsetPaginationMeta

12-api-contract.md §3.2 offset/limit pagination metadata, verbatim shape.

object

page

required

Page

integer

pageSize

required

Pagesize

integer

totalItems

required

Totalitems

integer

totalPages

required

Totalpages

integer

hasNext

required

Hasnext

boolean

hasPrev

required

Hasprev

boolean

Example^generated

{
  "items": [
    {
      "id": "example",
      "assignedUserId": "example",
      "customerId": "example",
      "conversationId": "example",
      "leadId": "example",
      "title": "example",
      "appointmentType": "example",
      "startsAt": "example",
      "endsAt": "example",
      "status": "example",
      "source": "example",
      "notes": "example",
      "createdAt": "example",
      "updatedAt": "example"
    }
  ],
  "total": 1,
  "pagination": {
    "page": 1,
    "pageSize": 1,
    "totalItems": 1,
    "totalPages": 1,
    "hasNext": true,
    "hasPrev": true
  }
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

Example^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}