Skip to navigation
Paperwork APIWork Sessions

Open a work session

View as Markdown

Opens a work session — one durable timeline that humans and named paperwork agents share.

Name the agents in agents (a handle such as mike, or an agt_ id); each must have a published version. They are mentioned with your description and their turns start before this call returns — startedTurnIds names them, and failedMentions names any agent whose turn could not be started. Open with an empty agents to invite nobody, then post to /entries when you are ready.

Give the session its working set in fileIds: every turn it runs is scoped to those files, so you never re-send them. With no spaceIds the session lives in your organization’s API workspace.

Set webhookUrl to receive this session’s events at one https endpoint, signed exactly like every other delivery. Your saved /v1/webhooks subscriptions receive them too.

Access is scoped to the API key that opened the session: another key of the same organization gets 404 on every route here. Set apiVisible: true to let every key of your organization read and write it.

Learn more: Work sessions

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
descriptionstringRequired1-8000 characters
titlestringOptional<=200 characters
agentslist of stringsOptionalDefaults to []
spaceIdslist of stringsOptionalDefaults to []
fileIdslist of stringsOptionalDefaults to []
webhookUrlstringOptionalformat: "uri"<=2048 characters
apiVisiblebooleanOptionalDefaults to false
metadatamap from strings to anyOptional

Response

The opened work session and the turns it started.
dataobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error
503
Service Unavailable Error