The Handovers API from 44pixels Limited — 15 operation(s) for handovers.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/handover-sh:handover-sh-handovers-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Handovers API
version: 1.16.0
description: Versioned context and revision-anchored review shared by humans and agents. Browser requests use the signed-in human session; agents authenticate with a scoped bearer credential.
servers:
- url: /api/v1
security:
- bearerAuth: []
tags:
- name: Handovers
paths:
/handovers/{id}/publication:
parameters:
- name: id
in: path
required: true
schema:
type: string
pattern: ^hov_
get:
operationId: getPublication
summary: Inspect a handover publication
responses:
'200':
description: Publication or null
tags:
- Handovers
put:
operationId: publishHandover
summary: Create or update a stable report projection
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicationInput'
responses:
'200':
description: Published report
'409':
$ref: '#/components/responses/Error'
tags:
- Handovers
delete:
operationId: unpublishHandover
summary: Remove a stable report projection
responses:
'204':
description: Publication removed
tags:
- Handovers
/handovers/{id}/okf:
parameters:
- name: id
in: path
required: true
schema:
type: string
pattern: ^hov_
get:
operationId: exportOkf
summary: Export an Open Knowledge Format bundle
parameters:
- name: revision
in: query
schema:
type: string
pattern: ^rev_
- name: format
in: query
schema:
type: string
enum:
- tar
- json
default: tar
responses:
'200':
description: OKF tar archive or JSON bundle
content:
application/x-tar: {}
application/json:
schema:
$ref: '#/components/schemas/OkfBundleEnvelope'
tags:
- Handovers
post:
operationId: importOkf
summary: Import OKF as an immutable revision
requestBody:
required: true
content:
application/x-tar: {}
application/json:
schema:
$ref: '#/components/schemas/OkfBundle'
responses:
'200':
description: Bundle was already imported
'201':
description: Bundle imported
tags:
- Handovers
/handovers:
get:
operationId: listHandovers
summary: Discover active handovers
parameters:
- name: q
in: query
description: Search across titles, summaries, revision notes, authors, artifact names, continuation briefs, and indexed text artifact content.
schema:
type: string
- name: mode
in: query
description: Hybrid combines lexical and semantic ranks. Hybrid falls back to lexical with modeUsed set accordingly when embeddings are unavailable.
schema:
type: string
enum:
- hybrid
- semantic
- lexical
default: hybrid
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 30
- name: cursor
in: query
schema:
type: string
- name: status
in: query
description: Lifecycle collection to list or search.
schema:
type: string
enum:
- active
- archived
- trashed
default: active
responses:
'200':
description: A page of handovers
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverPageEnvelope'
tags:
- Handovers
post:
operationId: createHandover
summary: Create a handover and its first immutable revision
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateHandover'
multipart/form-data:
schema:
$ref: '#/components/schemas/HandoverForm'
responses:
'201':
description: Created handover
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverEnvelope'
'400':
$ref: '#/components/responses/Error'
tags:
- Handovers
/handovers/{id}:
get:
operationId: getHandover
summary: Read a handover snapshot and its history
parameters:
- $ref: '#/components/parameters/HandoverId'
- name: revision
in: query
description: Read a specific immutable revision instead of the current one.
schema:
type: string
responses:
'200':
description: Handover snapshot
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverEnvelope'
'404':
$ref: '#/components/responses/Error'
tags:
- Handovers
delete:
operationId: purgeHandover
summary: Permanently purge a trashed handover after retention
description: Metadata is removed permanently. Content-addressed object bytes are deleted only when no remaining artifact references them.
parameters:
- $ref: '#/components/parameters/HandoverId'
responses:
'204':
description: Handover purged
'409':
description: The handover is not trashed or its retention window remains active.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
tags:
- Handovers
/handovers/{id}/access:
get:
operationId: getHandoverAccess
summary: Read visibility, explicit grants, and eligible organization participants
parameters:
- $ref: '#/components/parameters/HandoverId'
responses:
'200':
description: Handover access state
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverAccessEnvelope'
'404':
$ref: '#/components/responses/Error'
tags:
- Handovers
put:
operationId: updateHandoverAccess
summary: Set workspace or restricted visibility and replace explicit grants
description: Organization owners, the handover creator, and explicitly granted access owners can manage sharing.
parameters:
- $ref: '#/components/parameters/HandoverId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateHandoverAccess'
responses:
'200':
description: Updated handover access
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverAccessEnvelope'
'403':
$ref: '#/components/responses/Error'
tags:
- Handovers
/handovers/{id}/lifecycle:
post:
operationId: updateHandoverLifecycle
summary: Archive, restore, or move a handover to trash
description: Trash is reversible for 30 days. Trashed handovers cannot receive revisions.
parameters:
- $ref: '#/components/parameters/HandoverId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverLifecycleAction'
responses:
'200':
description: Updated handover snapshot
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverEnvelope'
'403':
$ref: '#/components/responses/Error'
tags:
- Handovers
/handovers/{id}/revisions:
post:
operationId: appendRevision
summary: Continue a handover with a new immutable snapshot
description: Artifacts omitted from the request are inherited from the current revision. An artifact with the same case-insensitive name replaces the previous artifact in the new snapshot.
parameters:
- $ref: '#/components/parameters/HandoverId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AppendRevision'
multipart/form-data:
schema:
$ref: '#/components/schemas/RevisionForm'
responses:
'201':
description: Updated handover
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverEnvelope'
'409':
description: The expected revision is stale.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
tags:
- Handovers
/handovers/{id}/thread:
get:
operationId: getHandoverThread
summary: Read comments, mentions, assignments, and collaborators
parameters:
- $ref: '#/components/parameters/HandoverId'
responses:
'200':
description: Handover collaboration thread
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverThreadEnvelope'
'404':
$ref: '#/components/responses/Error'
tags:
- Handovers
/handovers/{id}/comments:
post:
operationId: addHandoverComment
summary: Append a comment and notify explicit mentions
parameters:
- $ref: '#/components/parameters/HandoverId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddComment'
responses:
'201':
description: Updated collaboration thread
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverThreadEnvelope'
'403':
$ref: '#/components/responses/Error'
tags:
- Handovers
/handovers/{id}/annotations:
get:
operationId: listHandoverAnnotations
summary: List revision-anchored artifact comments
parameters:
- $ref: '#/components/parameters/HandoverId'
- name: artifactId
in: query
schema:
type: string
pattern: ^art_
- name: revisionId
in: query
schema:
type: string
pattern: ^rev_
- name: status
in: query
schema:
type: string
enum:
- open
- resolved
- stale
responses:
'200':
description: Filtered artifact annotations
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverThreadEnvelope'
tags:
- Handovers
post:
operationId: addHandoverAnnotation
summary: Add a comment anchored to an immutable artifact revision
parameters:
- $ref: '#/components/parameters/HandoverId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddAnnotation'
responses:
'201':
description: Updated collaboration thread
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverThreadEnvelope'
tags:
- Handovers
/handovers/{id}/comments/{commentId}:
patch:
operationId: updateHandoverComment
summary: Edit, resolve, or reopen a comment
parameters:
- $ref: '#/components/parameters/HandoverId'
- name: commentId
in: path
required: true
schema:
type: string
pattern: ^cmt_
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateComment'
responses:
'200':
description: Updated collaboration thread
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverThreadEnvelope'
'403':
$ref: '#/components/responses/Error'
tags:
- Handovers
/handovers/{id}/assignments:
put:
operationId: setHandoverAssignments
summary: Replace the open assignments for a handover
parameters:
- $ref: '#/components/parameters/HandoverId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SetAssignments'
responses:
'200':
description: Updated collaboration thread
content:
application/json:
schema:
$ref: '#/components/schemas/HandoverThreadEnvelope'
tags:
- Handovers
/handovers/{id}/assignments/{assignmentId}:
patch:
operationId: updateHandoverAssignment
summary: Complete or reopen one assignment
parameters:
- $ref: '#/components/parameters/HandoverId'
- name: assignmentId
in: path
required: true
schema:
type: string
pattern: ^asn_
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- action
properties:
action:
type: string
enum:
- complete
- reopen
responses:
'200':
description: Updated collaboration thread
tags:
- Handovers
/handovers/{id}/exports:
get:
operationId: getHandoverExportState
summary: List destinations and durable delivery history
parameters:
- $ref: '#/components/parameters/HandoverId'
responses:
'200':
description: Export state
tags:
- Handovers
post:
operationId: queueHandoverExport
summary: Queue an idempotent one-way revision export
description: The same destination and immutable revision resolve to one durable job. Provider delivery never changes Handover revision history.
parameters:
- $ref: '#/components/parameters/HandoverId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueueHandoverExport'
responses:
'202':
description: Queued or existing export state
'403':
$ref: '#/components/responses/Error'
tags:
- Handovers
/handovers/{id}/exports/{jobId}/retry:
post:
operationId: retryHandoverExport
summary: Retry a failed or dead-lettered export
parameters:
- $ref: '#/components/parameters/HandoverId'
- name: jobId
in: path
required: true
schema:
type: string
pattern: ^exp_
responses:
'202':
description: Updated export state
tags:
- Handovers
components:
schemas:
HandoverPageEnvelope:
type: object
required:
- data
properties:
data:
type: object
required:
- items
- nextCursor
properties:
items:
type: array
items:
$ref: '#/components/schemas/Handover'
nextCursor:
type:
- string
- 'null'
modeRequested:
type: string
enum:
- hybrid
- semantic
- lexical
modeUsed:
type: string
enum:
- hybrid
- semantic
- lexical
semanticAvailable:
type: boolean
HandoverEnvelope:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Handover'
HandoverThreadEnvelope:
type: object
required:
- data
properties:
data:
type: object
required:
- handoverId
- canWrite
- participants
- comments
- assignments
additionalProperties: true
AddAnnotation:
allOf:
- $ref: '#/components/schemas/AddComment'
- type: object
required:
- target
properties:
target:
$ref: '#/components/schemas/AnnotationTarget'
CreateHandover:
allOf:
- $ref: '#/components/schemas/RevisionInput'
- type: object
required:
- title
properties:
title:
type: string
summary:
type: string
RevisionInput:
type: object
properties:
note:
type: string
brief:
$ref: '#/components/schemas/ContinuationBrief'
artifactMode:
type: string
enum:
- merge
- replace
default: merge
artifacts:
type: array
minItems: 1
items:
$ref: '#/components/schemas/ArtifactInput'
UpdateHandoverAccess:
type: object
required:
- visibility
- grants
properties:
visibility:
type: string
enum:
- workspace
- restricted
grants:
type: array
items:
$ref: '#/components/schemas/HandoverGrantInput'
HandoverForm:
allOf:
- $ref: '#/components/schemas/RevisionForm'
- type: object
required:
- title
properties:
title:
type: string
summary:
type: string
AddComment:
type: object
required:
- body
properties:
body:
type: string
minLength: 1
maxLength: 10000
mentionPrincipalIds:
type: array
maxItems: 20
items:
type: string
pattern: ^prn_
target:
oneOf:
- $ref: '#/components/schemas/AnnotationTarget'
- type: 'null'
SetAssignments:
type: object
required:
- principalIds
properties:
principalIds:
type: array
maxItems: 20
items:
type: string
pattern: ^prn_
ErrorEnvelope:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
ContinuationBrief:
type: object
description: An immutable, structured snapshot of what a person or agent needs to resume the work.
properties:
objective:
type: string
currentState:
type: string
decisions:
type: array
items:
type: string
openQuestions:
type: array
items:
type: string
nextSteps:
type: array
items:
$ref: '#/components/schemas/ContinuationStep'
RevisionForm:
type: object
properties:
note:
type: string
brief:
type: string
description: JSON-encoded ContinuationBrief.
artifactName:
type: string
mediaType:
type: string
content:
type: string
files:
type: array
items:
type: string
format: binary
expectedRevisionId:
type: string
AnnotationTarget:
type: object
required:
- revisionId
- artifactId
- targetKind
- selector
properties:
revisionId:
type: string
pattern: ^rev_
artifactId:
type: string
pattern: ^art_
targetKind:
type: string
enum:
- text
- code
- html
selector:
$ref: '#/components/schemas/AnnotationSelector'
HandoverGrantInput:
type: object
required:
- principalId
- role
properties:
principalId:
type: string
pattern: ^prn_
role:
type: string
enum:
- viewer
- editor
- owner
UpdateComment:
type: object
minProperties: 1
properties:
body:
type: string
minLength: 1
maxLength: 10000
mentionPrincipalIds:
type: array
maxItems: 20
items:
type: string
pattern: ^prn_
target:
oneOf:
- $ref: '#/components/schemas/AnnotationTarget'
- type: 'null'
status:
type: string
enum:
- open
- resolved
resolvedRevisionId:
oneOf:
- type: string
pattern: ^rev_
- type: 'null'
OkfFile:
type: object
additionalProperties: false
required:
- path
- encoding
- content
properties:
path:
type: string
mediaType:
type: string
encoding:
type: string
enum:
- utf-8
- base64
content:
type: string
byteSize:
type: integer
minimum: 0
sha256:
type: string
QueueHandoverExport:
type: object
required:
- destinationId
properties:
destinationId:
type: string
pattern: ^dst_
revisionId:
type: string
pattern: ^rev_
PublicationInput:
type: object
additionalProperties: false
properties:
slug:
type: string
entryPath:
type: string
access:
type: string
enum:
- organization
- public
revisionMode:
type: string
enum:
- latest
- pinned
revisionId:
type: string
pattern: ^rev_
AnnotationSelector:
type: object
required:
- exact
properties:
exact:
type: string
minLength: 1
maxLength: 4000
prefix:
type: string
maxLength: 500
suffix:
type: string
maxLength: 500
startOffset:
type: integer
minimum: 0
endOffset:
type: integer
minimum: 0
startLine:
type: integer
minimum: 1
endLine:
type: integer
minimum: 1
OkfBundleEnvelope:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/OkfBundle'
Handover:
type: object
required:
- id
- title
- status
- visibility
- deletedAt
- purgeAfter
- currentRevisionId
- currentRevision
- revisions
additionalProperties: true
properties:
id:
type: string
title:
type: string
summary:
type: string
status:
type: string
enum:
- active
- archived
- trashed
visibility:
type: string
enum:
- workspace
- restricted
deletedAt:
type:
- string
- 'null'
format: date-time
purgeAfter:
type:
- string
- 'null'
format: date-time
currentRevisionId:
type: string
currentRevision:
type: object
additionalProperties: true
revisions:
type: array
items:
type: object
additionalProperties: true
HandoverLifecycleAction:
type: object
required:
- action
properties:
action:
type: string
enum:
- archive
- restore
- trash
HandoverAccessEnvelope:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/HandoverAccess'
ArtifactInput:
type: object
required:
- name
- content
properties:
name:
type: string
mediaType:
type: string
default: application/octet-stream
content:
type: string
encoding:
type: string
enum:
- utf8
- base64
default: utf8
HandoverAccess:
type: object
required:
- handoverId
- visibility
- canManage
- participants
properties:
handoverId:
type: string
pattern: ^hov_
visibility:
type: string
enum:
- workspace
- restricted
canManage:
type: boolean
participants:
type: array
items:
$ref: '#/components/schemas/HandoverAccessParticipant'
HandoverAccessParticipant:
type: object
required:
- principalId
- displayName
- type
- organizationRole
- isCreator
- isCurrentActor
properties:
principalId:
type: string
pattern: ^prn_
displayName:
type: string
type:
type: string
enum:
- human
- agent
- system
organizationRole:
type: string
enum:
- owner
- member
grantRole:
type:
- string
- 'null'
enum:
- viewer
- editor
- owner
- null
isCreator:
type: boolean
isCurrentActor:
type: boolean
OkfBundle:
type: object
required:
- files
properties:
okfVersion:
type: string
const: '0.1'
handoverId:
type: string
revisionId:
type: string
expectedRevisionId:
type: string
mode:
type: string
enum:
- merge
- replace
files:
type: array
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/OkfFile'
ContinuationStep:
type: object
required:
- id
- text
- status
properties:
id:
type: string
pattern: ^step_
text:
type: string
status:
type: string
enum:
- open
- done
AppendRevision:
allOf:
- $ref: '#/components/schemas/RevisionInput'
- type: object
properties:
expectedRevisionId:
type: string
parameters:
HandoverId:
name: id
in: path
required: true
schema:
type: string
pattern: ^hov_
responses:
Error:
description: Request error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: hnd_tok_<id>_<secret>
description: Scoped agent credential. Create it from the People & agents view; the secret is shown once.