Handoff
Working context for whoever picks a task up next — read the newest one of your kind before working a task, create one when you stop. Append-only: summary is the one line a person reads (what changed, what is next); body is JSON keyed by body.schema — nifty.checkpoint/1 is validated, any other <vendor>.<kind>/<version> is stored as-is. Newest of a kind wins; never edit an old one (there is no update). List with taskId and schema filters, limit: 1 for the latest.
List Handoffs
List taskHandoffs. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 3 fields. Ordered by -createdAt unless you pass sort.
Required scope: task-handoffs:read
query Parameters
projectIdRestrict the list to one project. Omit to list taskHandoffs across every project you can access.
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: -createdAt. Listing without projectId orders by -updatedAt instead.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
taskId[eq]Filter where taskId equals.
taskId[in]Filter where taskId is one of (comma-separated list).
schema[eq]Filter where schema equals.
schema[in]Filter where schema is one of (comma-separated list).
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
List Handoffs › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Create Handoff
Create a Handoff. Server-assigned fields are ignored if sent.
Required scope: task-handoffs:write
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create Handoff › Request Body
taskIdTask this hand-off belongs to. Required on create; immutable afterwards.
summaryOne line a person reads on the task: what changed and what is next. Plain text, at most 500 characters, no markdown.
Working context for whoever picks this task up next — a person or an agent. JSON at most 20,000 UTF-8 bytes, no string over 10,000 characters. body.schema names the kind: nifty.checkpoint/1 is validated, any other <vendor>.<kind>/<version> is stored as-is (the nifty. namespace is reserved). Newest of a kind wins; never edit an old one. Put decisions WITH their reasons, checks WITH their result, and one concrete next action.
Create Handoff › Responses
Created
idUnique identifier for this resource.
createdAtCreation timestamp.
taskIdTask this hand-off belongs to. Required on create; immutable afterwards.
schema^[a-z0-9][a-z0-9-]*\… · requiredThe kind of body, copied from body.schema when the hand-off is created — filter on it to find the newest hand-off of your kind. Read-only.
summaryOne line a person reads on the task: what changed and what is next. Plain text, at most 500 characters, no markdown.
Working context for whoever picks this task up next — a person or an agent. JSON at most 20,000 UTF-8 bytes, no string over 10,000 characters. body.schema names the kind: nifty.checkpoint/1 is validated, any other <vendor>.<kind>/<version> is stored as-is (the nifty. namespace is reserved). Newest of a kind wins; never edit an old one. Put decisions WITH their reasons, checks WITH their result, and one concrete next action.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
The related Task, present only when you pass ?expand=task.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Get Handoff
Retrieve a single Handoff by id.
Required scope: task-handoffs:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Handoff.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Handoff › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
taskIdTask this hand-off belongs to. Required on create; immutable afterwards.
schema^[a-z0-9][a-z0-9-]*\… · requiredThe kind of body, copied from body.schema when the hand-off is created — filter on it to find the newest hand-off of your kind. Read-only.
summaryOne line a person reads on the task: what changed and what is next. Plain text, at most 500 characters, no markdown.
Working context for whoever picks this task up next — a person or an agent. JSON at most 20,000 UTF-8 bytes, no string over 10,000 characters. body.schema names the kind: nifty.checkpoint/1 is validated, any other <vendor>.<kind>/<version> is stored as-is (the nifty. namespace is reserved). Newest of a kind wins; never edit an old one. Put decisions WITH their reasons, checks WITH their result, and one concrete next action.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
The related Task, present only when you pass ?expand=task.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Delete Handoff
Permanently delete this Handoff. This cannot be undone.
Required scope: task-handoffs:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Handoff.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Handoff › Responses
No Content