> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Remembered callers
> The people an agent remembers, and what it knows about them.
When memory is on, an agent remembers the people it talks to across calls and WhatsApp — so a caller
who gave their name last week is greeted by name today.
**Two halves, deliberately separate.** The *settings* — whether memory is on, which channels, which
fields to fill — are part of the agent's configuration and move with a publish. The *people* are
here, and are never versioned: an erasure has to take effect now, not at your next deploy.
Filter by the date a caller was last updated (`last_updated_on`, or `last_updated_from` /
`last_updated_to`) or search part of a number.
**Two different questions about channels.** The agent's `memory.channels` setting
(`inbound`, `outbound`, `whatsapp`) decides which conversations are *allowed* to feed memory -
a permission, and a phone call's direction is what it is judged on. A subject's `last_channel`
(`voice`, `whatsapp`) *records* how that person last got in touch. Widget conversations never
feed memory, so they appear in neither.
## OpenAPI
````yaml developers/openapi.json GET /v1/agents/{agent_id}/memory/subjects
openapi: 3.1.0
info:
title: Vocily API
description: >-
Public REST API for Vocily. Build and configure an agent, publish a version
and put it live, place outbound calls, and read back calls, chats and what
the agent remembered. Authenticate with a workspace API key as a Bearer
token.
Some things stay in the dashboard, by design: creating an API key, buying or
connecting a phone number, setting an agent's webhook URL, connecting
WhatsApp and its templates, building HTTP tools, and running batch
campaigns.
version: v1
servers:
- url: https://api.vocily.ai
description: Production
security: []
paths:
/v1/agents/{agent_id}/memory/subjects:
get:
tags:
- agent-memory
summary: List Subjects
description: >-
Callers this agent remembers, most recently seen first,
**cursor-paginated**.
Filter by the date they were last updated. `?offset=` is gone: memory is
written by live
calls, so a caller's position moves while you page and an offset repeats
or skips rows.
operationId: list_subjects_v1_agents__agent_id__memory_subjects_get
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
title: Agent Id
description: The agent's id, as `GET /v1/agents` returns it.
- name: last_updated_on
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: ISO date - callers updated that day
title: Last Updated On
description: ISO date - callers updated that day
- name: last_updated_from
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: ISO date - range start, inclusive
title: Last Updated From
description: ISO date - range start, inclusive
- name: last_updated_to
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: ISO date - range end, inclusive
title: Last Updated To
description: ISO date - range end, inclusive
- name: search
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Match any part of the number
title: Search
description: Match any part of the number
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
default: 100
title: Limit
description: Maximum records to return in one page.
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Opaque cursor from a previous response's `next_cursor`; omit for
the first page
title: Cursor
description: >-
Opaque cursor from a previous response's `next_cursor`; omit for the
first page
responses:
'200':
description: The callers this agent remembers.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
msisdn_full:
type: string
display_name:
type: string
nullable: true
fact_count:
type: integer
interaction_count:
type: integer
last_channel:
type: string
nullable: true
last_seen_at:
type: string
format: date-time
first_seen_at:
type: string
format: date-time
description: The rows on this page.
has_more:
type: boolean
description: Whether another page exists. `false` on the last.
next_cursor:
type: string
nullable: true
description: >-
Pass back as `?cursor=` for the next page; `null` on the
last one. **Opaque** — do not parse or construct one. A
cursor from a differently sorted list is refused with
`invalid_cursor` rather than silently returning page 1.
required:
- data
- has_more
example:
data: []
has_more: false
next_cursor: null
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
detail: Invalid API key
code: UNAUTHORIZED
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded — honor `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: rate_limited
security:
- bearerAuth: []
components:
schemas:
ApiError:
type: object
description: >-
Error envelope. `code` is derived from the HTTP status, so branch on it
for the CLASS of failure; the specific reason is `detail.code`. Every
public refusal carries both.
properties:
detail:
type: object
description: >-
The reason. `code` is the domain reason (e.g. `call_not_found`) and
`message` is a sentence safe to log. On a `422` it also carries
`errors[]`, one entry per rejected field — see
`HTTPValidationError`.
properties:
code:
type: string
example: call_not_found
message:
type: string
example: Call not found
required:
- code
- message
code:
type: string
description: Derived from the HTTP status, not the domain reason.
example: NOT_FOUND
HTTPValidationError:
type: object
title: HTTPValidationError
description: >-
A request the API could not read: a field of the wrong type, out of
range, missing, or one we do not accept. Same envelope as every other
error.
properties:
detail:
type: object
description: >-
What was wrong, as `code`, a one-line `message`, and every offending
field in `errors`.
required:
- code
- message
- errors
properties:
code:
type: string
enum:
- validation_error
message:
type: string
description: >-
The first problem in one line, with a count of the rest — e.g.
`model.temperature: Input should be less than or equal to 2 (and
1 more)`.
errors:
type: array
items:
$ref: '#/components/schemas/ValidationError'
description: >-
One entry per offending field. **Every problem is reported at
once**, not just the first, so a malformed body needs one round
trip to fix rather than one per field.
code:
type: string
enum:
- VALIDATION_ERROR
description: Derived from the HTTP status, as on every error.
ValidationError:
type: object
title: ValidationError
required:
- field
- message
- type
properties:
field:
type: string
description: >-
The offending field as a path from the root of your request —
`voice.speed`, `variables[0].key`, or `query.limit` for a query
parameter. **This is the field to read.**
message:
type: string
description: What is wrong with it, in plain language.
type:
type: string
description: >-
A stable machine code for the kind of failure, e.g.
`extra_forbidden` for a field we do not accept, `missing` for a
required one, or `less_than_equal` for a number out of range. Switch
on this rather than on `message`, which may be reworded.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.'
````