API de docket

attachment.get

POST /agent/tools/attachment.get

Read one attachment: { attachment, url, grund }. Over MCP an image up to 5 MB comes as image content and a text file up to 256 KB as text content; otherwise url is a download link valid for 5 minutes. Without object storage url is null and grund is kein-object-storage. An unknown attachment is DOCKET_ATTACHMENT_NOT_FOUND.

Tipo

lectura

Derecho

docket:item:read

Tipos de key

agent maintenance observer

Entrada

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

attachment.list

POST /agent/tools/attachment.list

List the attachments of an item (screenshots, PDFs, text files), oldest first: { id, itemId, fileName, mimeType, sizeBytes, authorId, createdAt }. Read one with attachment.get.

Tipo

lectura

Derecho

docket:item:read

Tipos de key

agent maintenance observer

Entrada

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

cloneRequest.next

POST /agent/tools/cloneRequest.next

Fetch the oldest open clone request of your machine and mark it claimed. Returns { request: { id, repos: [{ repo, path, knowledge? }] } } (path relative to your work root, "." = the root repo, null = none set; knowledge: true marks a knowledge base of the group, a code repo has no such field) or { nothing: true }. Clone each repo, then call cloneRequest.report.

Tipo

escritura

Derecho

docket:lease:write

Tipos de key

agent

Entrada

Sin campos; el cuerpo es {}.

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

cloneRequest.report

POST /agent/tools/cloneRequest.report

Report the result of a claimed clone request: one entry per repo of the request (result cloned, exists, exists-other-remote or failed; reason only with failed or exists-other-remote). A missing, doubled or foreign repo is DOCKET_CLONE_REPORT_MISMATCH. Returns { status } (failed as soon as one repo failed, otherwise done).

Tipo

escritura

Derecho

docket:lease:write

Tipos de key

agent

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

customerRequest.import

POST /agent/tools/customerRequest.import

Import a customer request (KW-n) from the register with its fixed number, title, optional description, received date and linked items of the same group. A number already taken is a conflict. Setup keys only.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

dashboard.get

POST /agent/tools/dashboard.get

Dashboard of a project, a group or the whole organisation (target { kind: "org" } without id: all projects you can see; the answer names the organisation id): counts by status and priority, counts by status per project, epics, what waits for you, work in progress (item, item number, machine, lane, lease end, last report, last signal), machines (last heartbeat, load), usage of the last 7 days per project and approved items that cannot be claimed (without repos, open need, waiting for an answer), the latest merge train and merged version per repo of the group (organisation: of the groups of the projects you can see), and pull requests waiting for review with their item, project, effective priority and item status (oldest first, at most 100); questions for you and assigned to you carry the effective priority and status of their item (null without item).

Tipo

lectura

Derecho

docket:item:read

Tipos de key

maintenance observer setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

deploy.list

POST /agent/tools/deploy.list

List the deploy services of the organisation by name, each with the running versions { backend, frontend }, the open candidate (ready or approved) and the last done candidate (null if none).

Tipo

lectura

Derecho

docket:item:read

Tipos de key

deploy-candidate maintenance observer

Entrada

Sin entrada.

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

deploy.markDone

POST /agent/tools/deploy.markDone

Mark a deploy candidate done after the deploy has run: only for a service deployed by the observer (else DOCKET_DEPLOY_DONE_BY_TORSTEN), and without standing approval only once a human approved it (else DOCKET_DEPLOY_NOT_APPROVED). The versions become the running versions of the packages; pull requests with "Needs-deployed:" on them are re-evaluated. Done or superseded ⇒ DOCKET_DEPLOY_CANDIDATE_CLOSED. Returns the candidate.

Tipo

escritura

Derecho

docket:deploy:report

Tipos de key

deploy-candidate observer

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

deploy.reportCandidate

POST /agent/tools/deploy.reportCandidate

Report the versions of a service that are ready to deploy (service: its name; backendVersion and frontendVersion: SemVer up to 50; frontendVersion only for a service with a frontend package, else DOCKET_DEPLOY_NO_FRONTEND). The open candidate of the service becomes superseded. Unknown service ⇒ DOCKET_DEPLOY_SERVICE_UNKNOWN. Returns { candidate, supersededId }.

Tipo

escritura

Derecho

docket:deploy:report

Tipos de key

deploy-candidate observer

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

deploy.serviceCreate

POST /agent/tools/deploy.serviceCreate

Create a deploy service of the organisation (admin). name: slug up to 60 characters, stored lower-case and unique in the organisation (else DOCKET_DEPLOY_SERVICE_EXISTS); backendPackage and frontendPackage: npm names up to 214 characters (frontendPackage null = no frontend); deployedBy: observer (deployed with a deploy-candidate key) or torsten (deployed by a human, marked done in the browser); standingApproval: the observer deploys without a human approval of each candidate. Returns the service.

Tipo

escritura

Derecho

docket:org:manage

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

deploy.serviceUpdate

POST /agent/tools/deploy.serviceUpdate

Change a deploy service (admin); only the given fields. name: slug up to 60 characters, stored lower-case and unique in the organisation (else DOCKET_DEPLOY_SERVICE_EXISTS); backendPackage and frontendPackage: npm names up to 214 characters (frontendPackage null = no frontend); deployedBy: observer (deployed with a deploy-candidate key) or torsten (deployed by a human, marked done in the browser); standingApproval: the observer deploys without a human approval of each candidate. Nothing changed ⇒ nothing is written. Returns { service, changed, fields }.

Tipo

escritura

Derecho

docket:org:manage

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

deployedVersion.report

POST /agent/tools/deployedVersion.report

Report the version of a package that runs now, after a deploy (package: npm name up to 214 characters, version: SemVer 2.0 up to 50). One row per package and organisation: the report replaces the previous version, also with a lower one (rollback); the same version again is no error. Pull requests with a "Needs-deployed:" line on the package are re-evaluated at once: a ready one whose need no longer holds returns to waiting for needs, one in a train stays. "Needs:" lines keep measuring published versions. Returns { id, package, version, reportedBy, at }.

Tipo

escritura

Derecho

docket:merge:report

Tipos de key

merge-session

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

epic.import

POST /agent/tools/epic.import

Import an epic (EP-n) from the register: the epic with that number, else the one titled EP-NNN in the group, else a new one; sets number, title, description, area and start date and links the given items of the group. Setup keys only.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

epic.list

POST /agent/tools/epic.list

List the epics you can see, optionally in one group, each with its number, area, start date and progress over its items.

Tipo

lectura

Derecho

docket:item:read

Tipos de key

maintenance observer setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

githubRepo.add

POST /agent/tools/githubRepo.add

Register a GitHub repository (owner/name) for a project group; docket then accepts its webhooks.

Tipo

escritura

Derecho

docket:org:manage

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

githubRepo.list

POST /agent/tools/githubRepo.list

List the GitHub repositories of a project group, each with majorBacklog { count, oldestSince, due }: items merged to a branch other than main that wait for the major cut.

Tipo

lectura

Derecho

docket:org:manage

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

githubRepo.listForOrg

POST /agent/tools/githubRepo.listForOrg

List every GitHub repository of the organisation (any of them can be added to an item): repo, path, groupId, and groupName (null for groups outside your access).

Tipo

lectura

Derecho

docket:item:read

Tipos de key

agent maintenance observer

Entrada

Sin entrada.

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

githubRepo.move

POST /agent/tools/githubRepo.move

Move a registered repository to another project group of the organisation, together with its pull requests and merge trains; secret, path and lease lock stay. Same group ⇒ changed false. A running merge train of the repository ⇒ DOCKET_GITHUB_REPO_BUSY.

Tipo

escritura

Derecho

docket:org:manage

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

githubRepo.setLeaseLock

POST /agent/tools/githubRepo.setLeaseLock

Switch the lease lock of a registered repository (owner/name) of a project group: false ⇒ lanes may work on it at the same time, true ⇒ one lane at a time. Same value ⇒ changed false.

Tipo

escritura

Derecho

docket:org:manage

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

githubRepo.webhookSecret

POST /agent/tools/githubRepo.webhookSecret

Return the webhook secret of a registered repository; creates it once if the repository has none.

Tipo

escritura

Derecho

docket:org:manage

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.addNeed

POST /agent/tools/item.addNeed

Record that itemId needs needsItemId (P-n or uuid): lease.claim hands out itemId only once needsItemId is released or done. Owner of the project of itemId (an org admin only with a setup key; over an agent key the org role is always member); needsItemId must be visible to you. Already there ⇒ no change; a cycle (also the item itself) ⇒ DOCKET_NEED_CYCLE. Returns { itemId, needs }.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

agent maintenance observer setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.addRepo

POST /agent/tools/item.addRepo

Add one GitHub repo (owner/name) to an item. The repo must be registered in the organisation, in any group (else DOCKET_ITEM_REPO_UNKNOWN; its reason names the repo and the way to register it: docket-cli github setup --repo <owner/name>, githubRepo.add); already there (case-insensitive) ⇒ changed false; while a lane holds the item ⇒ DOCKET_ITEM_REPOS_LEASED. Setup keys only.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

maintenance setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.comment

POST /agent/tools/item.comment

Comment on an item as a whole (no anchor, any status). It does not block approval and shows in the item history. With toLane: true the comment goes to the lane: lease.claim returns the open lane comments of the item in comments, lease.renew those written since the last claim or renew.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

agent api maintenance observer

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.correctImportStatus

POST /agent/tools/item.correctImportStatus

Correct the status of an item that item.import set wrongly: approved becomes released. Only for an imported item that never left approved and has no active lease and no open pull request. reason says why (kept in the audit log). Setup keys only.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.correctReleasedStatus

POST /agent/tools/item.correctReleasedStatus

Set a released item back to approved when its release report carried no version (released without --version on an item with one repo). Only when the last lease of the item ended with a released report without versions; otherwise DOCKET_RELEASE_CORRECTION_HAD_VERSION, DOCKET_RELEASE_CORRECTION_NOT_REPORTED (released by the merge train or by import) or DOCKET_RELEASE_CORRECTION_NOT_RELEASED. Allowed for the owner of the project (an org admin only in the browser: over an agent key the org role is always member) and for the key whose lease ended with released; note is required and becomes a comment on the item. Returns { item }.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

agent

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.create

POST /agent/tools/item.create

Create an item (design, plan or issue) in a project, optionally in an epic and with its GitHub repos (owner/name). The rank is set by a human. If the group does not require approval, the item starts approved.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.createDraft

POST /agent/tools/item.createDraft

Create a draft item (design, plan or issue) in a project, optionally with its GitHub repos (owner/name). The item starts in status "draft". A repo not registered in the organisation is a 422 DOCKET_ITEM_REPO_UNKNOWN whose reason names it; an org admin registers it with a setup key: docket-cli github setup --group <group> --machine <machine> --repo <owner/name> (githubRepo.add). The head of body (the text before the first line starting with "## ") may link customer requests and an epic: a line "**Kundenwunsch**: KW-12, KW-14" links every KW-n of the line, a line "**Epic**: EP-3" sets the epic; both must belong to the group of the project. The answer then carries customerRequests (id, number, title) and the inherited effectivePriority; two different epics are a 400 on body. A line "**Nicht vor**: YYYY-MM-DD" in the head sets the not-before date (Europe/Berlin): lease.claim hands the item out only from that day on (reason not-before); an invalid date or two dates is a 400 DOCKET_ITEM_NOT_BEFORE_INVALID on body. A line "**Fällig**: YYYY-MM-DD" in the head sets the due date of the item, optionally with "**Erinnern ab**: YYYY-MM-DD" (remind from, at most the due date; without it the dashboard reminds 14 days before); an invalid date, two due dates or a reminder without a due date is a 400 DOCKET_ITEM_DUE_INVALID on body. "**Frist**: YYYY-MM-DD" counts like "**Fällig**", but only with a plain date; any other value stays text. item.get and item.list return dueAt and remindFrom. derivedFrom (at most 10 designs, uuid or P-n) links a new plan to the designs it comes from; anything but design to plan is DOCKET_LINK_INVALID.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

agent api maintenance observer

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.deferImported

POST /agent/tools/item.deferImported

Defer an item that item.import created: lease.claim no longer hands it out until a human clears it (item.clearDeferred). Only for an imported item that never left approved and has no active lease and no open pull request; the status stays approved. reason says why (shown on the dashboard, kept in the audit log). Already deferred: the old reason stays and changed is false. Setup keys only.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.delete

POST /agent/tools/item.delete

Delete an item with everything attached to it (author, owner or admin). A lane holds it or its pull request is in a running merge train ⇒ DOCKET_ITEM_BUSY; in progress ⇒ DOCKET_FORBIDDEN. Call item.deletePreview first: it counts what goes with it.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

maintenance

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.deletePreview

POST /agent/tools/item.deletePreview

Count what item.delete would remove with the item and whether it is busy (never DOCKET_ITEM_BUSY); same rights as item.delete, also while the item is in progress.

Tipo

lectura

Derecho

docket:item:write

Tipos de key

maintenance

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.firstTrees

POST /agent/tools/item.firstTrees

For every precedence (first) set on an item, an epic or a customer request you can see, how much of its need tree could run in parallel now: [{ kind (item, epic or customerRequest), id, number, title, firstAt, parallel { startNow, waitingNeed, waitingRepo, waitingOther, inProgress }, truncated }], oldest firstAt first, at most 20. An epic or customer request counts only with at least one item you can see; nodes in projects you cannot see do not count. truncated: true if the tree has more than 500 nodes (only the loaded ones count). A hint only: lease.claim hands out as before.

Tipo

lectura

Derecho

docket:item:read

Tipos de key

agent maintenance observer setup

Entrada

Sin entrada.

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.get

POST /agent/tools/item.get

Read one item with all revisions and your effective roles in its project, plus its pull requests (repo, number, status, readiness reason, needs, train, review of the current head; at most 100) and neededBy (the items that need this one, with project and group; items you cannot read only as the count neededByHidden), and lastLeaseEndReason (why its last ended lease ended, e.g. waiting-for-answer or fulfilled; null if none), and prNeeds: the Needs/Needs-deployed lines of its open pull requests (not closed, merged or invalid) as one entry per package, op, version and deployed, each with resolved (the smallest published, or for deployed the running, version that satisfies it; null if none) and prs (<repo>#<n> of the open pull requests that carry it), and waitsForMajor: the target branch of a merged pull request of the current revision that went to a branch other than main and waits for the next major release of its repo (null if none; such an approved item is not claimable, reason waits-for-major), and latestStage: how far the item got, derived and never stored (null without any lease or report): stage started (a lease or a report), implemented (an open or draft pull request in its repos, also after a release, or a pr-opened report), merged (every repo of the item merged or unchanged), released (every repo done and at least one real version; releases lists { repo, package, version }, package null from a released report) or deployed (a deploy service with that package ran a version at least as high by semver; deployed { service, version, at } of the earliest such deploy, else null); noRelease lists the repos done without a release (no-release, no train, train expired). A pull request closed without merge does not count.

Tipo

lectura

Derecho

docket:item:read

Tipos de key

agent api maintenance observer setup

Entrada

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.history

POST /agent/tools/item.history

Read the history of one item, newest first: status changes, leases (machineName, lane, endedAt, endReason, rework: true for a lease claimed to rework a pull request), reports (with prs [{ repo, number }] and versions of the report, also on an item named in alsoItems), revisions, audit events and free comments (comment with commentId, authorId, the whole text and toLane), at most limit entries (1–200, default 100). trackedSince is the oldest recorded status change of the organisation. Use it to read back a comment you wrote with item.comment.

Tipo

lectura

Derecho

docket:item:read

Tipos de key

agent api maintenance observer

Entrada

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.import

POST /agent/tools/item.import

Import an item from its source file in its target status (approved, released or done) without review, optionally with rank, priority immediately (only with a KW-NNN entry in customerRequests), customerRequests naming customer requests KW-NNN of the group of the project (each linked to the item; never created, unknown is 404 DOCKET_CUSTOMER_REQUEST_NOT_FOUND, one of another group 403; tags is the deprecated old name of customerRequests with the same meaning, both at once is 400), an existing epic of the group of the project (epicTitle EP-NNN matches the epic number, any other text the exact title; never created, unknown is 422 DOCKET_EPIC_UNKNOWN), its GitHub repos and, only with status approved, deferredReason to create it deferred (lease.claim skips it until a human clears it). With sourceRef (REQUIREMENTS/….md@<sha>) a repeat is safe: the path without the sha is unique per organisation, and a known path writes nothing, runs no other check and answers imported false with the existing item, its current revision and status. Setup keys only.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.lineage

POST /agent/tools/item.lineage

Read where an item comes from and what came from it: derivedFrom (designs) and derived (plans), each with id, number, kind, title, status and projectId. Items you cannot see only count in hidden.

Tipo

lectura

Derecho

docket:item:read

Tipos de key

agent maintenance observer setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.link

POST /agent/tools/item.link

Link a plan to the design it comes from: from is the design, to the plan (uuid or P-n). You need write access to both projects; other kinds or the item itself ⇒ DOCKET_LINK_INVALID, more than 50 plans per design or 10 designs per plan as well. An existing link is no error.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

agent setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.list

POST /agent/tools/item.list

List items you can see, optionally filtered by project, group, status, kind, priority, epic or machine. Project, status, kind, priority, epic and machine take one value or a list (any of them); filters combine with AND; machine means an active lease on that machine. forGroup (a group id) lists the work for that group in projects of other groups: items that an item of the group needs. Each item lists its lease (machineId, machineName, lane of its active lease, or null) and lastLeaseEndReason (why its last ended lease ended, or null), plus notClaimable: why an approved item is not claimable (waits-for-major, deferred, without-repos, open-need, waiting-for-answer, given-up-recently; the same reasons as dashboard.get, [] if claimable or not approved), and givenUp: { until, note, lane, machineName } of the given-up-recently block (end of the block, the note, the lane and the machine name of the given-up lease, the same as dashboard.get) exactly when notClaimable has given-up-recently, otherwise null. notClaimable: true lists only items with a reason, false only items without one. Each item also lists prNeeds, waitsForMajor and latestStage as item.get does; needsPackage (an npm name) lists only items with an unresolved need for that package in an open pull request, needsVersion only those whose unresolved need names exactly that version.

Tipo

lectura

Derecho

docket:item:read

Tipos de key

agent api maintenance observer setup

Entrada

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.markDone

POST /agent/tools/item.markDone

Mark an item done: released → done, or in progress → done after a fulfilled lease (owner of the project). Returns the item. Not while the item is in progress over a maintenance key (DOCKET_FORBIDDEN).

Tipo

escritura

Derecho

docket:item:write

Tipos de key

maintenance

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.markSuperseded

POST /agent/tools/item.markSuperseded

Mark an item as superseded, either by another item (by: the item that replaces it or already did the work; note optional) or by work outside docket (byRef: a plan path, tag/SHA or decision, 1-300 characters; note required). Exactly one of by and byRef. The item goes to the final status superseded and loses its deferredReason; lease.claim never hands it out again, and a need on it counts as met when the chain ends at a byRef. From draft, in review, approved, in progress or superseded; released is DOCKET_INVALID_TRANSITION, and so is done, except with byRef for an owner of the project when the last lease of the item ended fulfilled (closes an item that was only marked done because nothing replaced it). While a lease holds the item it is DOCKET_ITEM_BUSY, unless leaseId names your own active lease on this item: that lease then ends with superseded. Use this instead of lease.release with deferred when you find the item replaced. On a superseded item the same by or byRef changes nothing, another one overwrites. Returns { item, changed }.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

agent maintenance observer

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.move

POST /agent/tools/item.move

Move an item to another project of the organisation (owner or admin at source and target). Number, revisions, history, comments, approvals, tags, needs, pull requests and leases stay; its questions and usage rows move along. Same project ⇒ changed false. An epic or customer request of another group than the target ⇒ DOCKET_EPIC_NOT_IN_GROUP / DOCKET_ITEM_NOT_IN_GROUP, unless unlink: true (then the link is removed and named in unlinkedEpic / unlinkedCustomerRequests). A lane holding the item or a running merge train of its PRs ⇒ DOCKET_ITEM_BUSY. Setup keys only.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

maintenance setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.needTree

POST /agent/tools/item.needTree

The tree of what an item, an epic or a customer request needs (exactly one of itemId, epicId, customerRequestId; an epic or customer request starts at its items you can see). Returns rootIds and flat nodes { itemId, number, title, status, priority, effective: { priority, source, firstAt }, met, notClaimable, stuckReason, children }: children are the item ids the node needs (a superseded item counts as the end of its replacement chain), met means released or done, and a met node comes without its children. effective is the priority with precedence (first) and what the node inherits from the open items that need it. Each node also has repos, wave (1 if no child is open, else 1 + the largest wave of its open children; null when met) and parallelNow (could start now without sharing a repo with a node chosen before it). parallel { startNow, waitingNeed, waitingRepo, waitingOther, inProgress } counts every open node once. A hint only: lease.claim hands out as before. At most 500 nodes, truncated: true if there were more.

Tipo

lectura

Derecho

docket:item:read

Tipos de key

agent maintenance observer setup

Entrada

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.removeNeed

POST /agent/tools/item.removeNeed

Remove the need itemId → needsItemId (P-n or uuid). Owner of the project of itemId (an org admin only with a setup key; over an agent key the org role is always member); missing ⇒ no change. Returns { itemId, needs }.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

agent maintenance observer setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.removeRepo

POST /agent/tools/item.removeRepo

Remove one GitHub repo (owner/name) from an item (case-insensitive). Not on the item ⇒ changed false; while a lane holds the item ⇒ DOCKET_ITEM_REPOS_LEASED. Setup keys only.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

maintenance setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.rename

POST /agent/tools/item.rename

Change the title of an item (author, owner or admin; any status, no new revision). The same title after trimming ⇒ changed false. Not while the item is in progress (DOCKET_FORBIDDEN). Returns { item, changed }.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

maintenance observer

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.revise

POST /agent/tools/item.revise

Add a new revision (full text) to an item. Through a key only in status "draft" or "in review"; "repos" (owner/name) only in status "draft". A repo not registered in the organisation is a 422 DOCKET_ITEM_REPO_UNKNOWN whose reason names it; an org admin registers it with a setup key: docket-cli github setup --group <group> --machine <machine> --repo <owner/name> (githubRepo.add). A line "**Nicht vor**: YYYY-MM-DD" in the head sets the not-before date (Europe/Berlin): lease.claim hands the item out only from that day on (reason not-before); an invalid date or two dates is a 400 DOCKET_ITEM_NOT_BEFORE_INVALID on body. A line "**Fällig**: YYYY-MM-DD" in the head sets the due date of the item, optionally with "**Erinnern ab**: YYYY-MM-DD" (remind from, at most the due date; without it the dashboard reminds 14 days before); an invalid date, two due dates or a reminder without a due date is a 400 DOCKET_ITEM_DUE_INVALID on body. "**Frist**: YYYY-MM-DD" counts like "**Fällig**", but only with a plain date; any other value stays text. item.get and item.list return dueAt and remindFrom. A revision without the marker keeps the stored dates. While you hold the action lease "revise" of the item the revision also works in status "in progress" and ends the lease (status "in review"). A lease of another lane on an action ⇒ DOCKET_ITEM_HELD_BY_LANE with its name.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

agent maintenance observer setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.setDue

POST /agent/tools/item.setDue

Set or clear the due date of an item (dueAt and remindFrom as YYYY-MM-DD or null; owner or admin; no new revision). Invalid ⇒ DOCKET_ITEM_DUE_INVALID; the same values ⇒ changed false. Not while the item is in progress (DOCKET_FORBIDDEN).

Tipo

escritura

Derecho

docket:item:write

Tipos de key

maintenance

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.setNotBefore

POST /agent/tools/item.setNotBefore

Set or clear the not-before date of an item (YYYY-MM-DD or null; lease.claim hands it out only from that day; owner or admin; no new revision). Invalid ⇒ DOCKET_ITEM_NOT_BEFORE_INVALID; the same value ⇒ changed false. Not while the item is in progress (DOCKET_FORBIDDEN).

Tipo

escritura

Derecho

docket:item:write

Tipos de key

maintenance

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

item.unlink

POST /agent/tools/item.unlink

Remove a link between a design and a plan (uuid or P-n). Same rights as item.link; removing a link that does not exist is no error.

Tipo

escritura

Derecho

docket:item:write

Tipos de key

agent setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

knowledgeRepo.add

POST /agent/tools/knowledgeRepo.add

Register a knowledge base repository of the organisation: { repo, path?, entry? } (path relative to the work root, entry the file to read first, default wiki/index.md). Returns { id, repo, path, entry, uses }. A repository already registered is KNOWLEDGE_REPO_TAKEN.

Tipo

escritura

Derecho

docket:org:manage

Tipos de key

setup

Entrada

Sin entrada.

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

knowledgeRepo.list

POST /agent/tools/knowledgeRepo.list

List the knowledge bases of the organisation, each { id, repo, path, entry, uses }, sorted by repo.

Tipo

lectura

Derecho

docket:org:manage

Tipos de key

setup

Entrada

Sin entrada.

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

knowledgeRepo.listForGroup

POST /agent/tools/knowledgeRepo.listForGroup

Read the knowledge of a project group: { assigned, knowledge }. knowledge is the resolved chain over uses, each { repo, path, entry }, base first; read the entry files in this order before you work.

Tipo

lectura

Derecho

docket:item:read

Tipos de key

agent maintenance observer setup

Entrada

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

knowledgeRepo.setForGroup

POST /agent/tools/knowledgeRepo.setForGroup

Assign knowledge bases to a project group: { projectGroupId, repos } replaces the whole list (at most 20; usually one, the lowest). Returns { changed, knowledge } with the resolved chain, base first. Same errors as knowledgeRepo.setUses.

Tipo

escritura

Derecho

docket:org:manage

Tipos de key

setup

Entrada

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

knowledgeRepo.setUses

POST /agent/tools/knowledgeRepo.setUses

Set the knowledge bases a knowledge base builds on: { repo, uses } replaces the whole list (at most 20). A cycle is KNOWLEDGE_CYCLE, a chain deeper than 5 KNOWLEDGE_TOO_DEEP, more than 20 resolved knowledge bases at a group KNOWLEDGE_TOO_MANY, an unknown name KNOWLEDGE_NOT_FOUND. Returns { knowledgeRepo, changed }.

Tipo

escritura

Derecho

docket:org:manage

Tipos de key

setup

Entrada

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

lease.claim

POST /agent/tools/lease.claim

Claim the next approved item of a project, a group or all your targets (target "all" needs a priority) for a lane, or exactly one item by id (target { item }); target { item } also claims an item in progress without a lease whose last lease ended pr-opened, so you can report released or rework the pull request (the status stays in progress). Name the project by id or as "<group-slug>/<project-slug>", the group by id or slug; a target that is unknown or outside your targets is DOCKET_TARGET_UNKNOWN. Returns the item, its approved revision, repos, answered lane questions, openPrs (the open pull requests of the item with repo, number, branch, status and reason; keep working on those branches instead of opening new ones; [] if none), comments (the open lane comments of the item: id, text, authorId, createdAt; [] if none), webhookMissing (the repos of the item docket never received a webhook from, so no merge train will pick up their pull requests; absent if none; the claim is not refused) and a lease of 30 minutes, or { nothing: true }; for target { item } with reasons (the blocks: not-approved, in-progress (in progress and leased, or not after pr-opened), pr-open (after pr-opened the merge train still has an open pull request of the item and reports the release), superseded, design-session-only (designs and items with a requested action are only handed to design sessions), no-requested-action (a design session only gets items with a requested action), deferred, without-repos, open-need, waiting-for-answer, repo-leased, repos-unknown, not-in-key-targets); with repo-leased also leasedRepos ([{ repo, leaseId, itemId, itemNumber, lane, since }]: each repo of the item an active lease holds, the holding lease, its item (itemNumber = P-n, null without a number), lane and start). Optional repos (owner/name, case-insensitive) lists the repos your lane can start: items with a repo outside the list are skipped, and the answer names them in skipped ([{ itemId, repos }] with the missing repos, also with { nothing: true }); for target { item } a missing repo is the block repos-unknown. With rework: true (only with target { item }, otherwise BAD_REQUEST) the claim also takes an item in progress whose merge train still has its pull request open (no block pr-open), so you can rework that pull request; end the lease with pr-opened for the same pull request. The lease carries rework. Optional session is work (the default) or design: a design session gets only items with a requested action, a work session never gets those and never a design. The answer carries action (revise, plan or null) and, for revise, annotations (the open anchored annotations: id, revision, startLine, endLine, quote, text, authorId, createdAt, anchorLost; oldest first, at most 100; [] otherwise) with annotationsTruncated. knowledge lists the knowledge bases of the group of the item in reading order, base first ([{ repo, path, entry }]: path relative to your work root like a repo path, null = none set; entry is the file to read first; [] if the group has none). plugins lists the Claude Code plugins of the group of the item ([{ package, plugin, version }]: an npm package, a plugin in it and latest or a fixed version; sorted by package and plugin; [] if the group has none). docketPlugin says whether the lane loads the docket plugin of docket-cli before plugins (a switch of the group, true by default and without a group).

Tipo

escritura

Derecho

docket:lease:write

Tipos de key

agent

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

lease.release

POST /agent/tools/lease.release

Give your lease back with a note; the item returns to "approved". With waitingForAnswer only if a lane question of this lease is open. With deferred the note becomes the reason the item is deferred: lease.claim skips it (block deferred) until a human clears it; no question, no mail. deferred and waitingForAnswer together are invalid. With quota you hand the item over because your account quota is nearly used up (report kind handover first): the lease ends with "quota" and the item returns to "approved" for the next lane; quota is invalid together with deferred or waitingForAnswer.

Tipo

escritura

Derecho

docket:lease:write

Tipos de key

agent

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

lease.renew

POST /agent/tools/lease.renew

Renew your lease to now + 30 minutes. Returns comments: the lane comments of the item written since your claim or last renew (id, text, authorId, createdAt; [] if none), and annotations: on a lease with the action revise the open annotations written since then, in the form of lease.claim ([] otherwise). An ended lease answers DOCKET_LEASE_ENDED with the reason.

Tipo

escritura

Derecho

docket:lease:write

Tipos de key

agent

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

machine.create

POST /agent/tools/machine.create

Register a machine for the owner of the key (name, unique per owner regardless of case).

Tipo

escritura

Derecho

docket:lease:write

Tipos de key

setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

machine.heartbeat

POST /agent/tools/machine.heartbeat

Heartbeat of your machine with its load (cpu = load average 1 min per core, free memory and free disk in GB). Send it every 5 minutes.

Tipo

escritura

Derecho

docket:report:write

Tipos de key

agent

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

machine.list

POST /agent/tools/machine.list

List machines with their keys (never the key secret).

Tipo

lectura

Derecho

docket:item:read

Tipos de key

maintenance observer setup

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

merge.claim

POST /agent/tools/merge.claim

Claim the next merge train in the named project groups (id or slug) whose merge session runs on your machine: one repo, up to 100 ready pull requests in the order they became ready (prId, number, branch, headSha, itemId, needs; each need carries resolved, the smallest published version that satisfies it; for a need with deployed: true from a Needs-deployed: line the version that runs now, reported by deployedVersion.report; checks: unknown when GitHub reported no check_run or status at its head, pending while one is open, else success), and a train lease of 60 minutes, or { nothing: true }. A ready pull request with a failed check_run or status at its current head stays ready and out of the train with reason checks-failed: <names> (the failed check names, sorted, comma separated). A ready pull request whose target branch is not main (the release branch; no base counts as main) stays ready and out of the train with reason target-branch: <branch>; its checks are not read, and an active lease of its item still wins with lease-active. When a train goes, it carries skipped (up to 50 such pull requests of the train repo, ordered by repo and number, each with repo, number and reason) only when there is one. Optional repos (owner/name, 1 to 100, no duplicates ignoring case) limits the claim to ready pull requests of these repos in the named groups; the comparison ignores case, and a repo outside the groups is no error, only no match. With repos, { nothing: true } carries skipped: up to 50 pull requests of these repos in the named groups that did not go (not closed or merged), ordered by repo and number, each with repo, number and reason (its invalid code such as DOCKET_PR_LINE_MISSING for a pull request on a branch docket/<item id>-… without a Docket line, else its readiness reason such as draft or revision-mismatch while it waits, else its status such as red; a pull request in a train has reason in train with trainId); a ready pull request whose item a lane still holds under an active lease has reason lease-active, a ready one whose repo already has a running train has reason train-running (with trainId when that train runs in one of the named groups), and a ready one whose row a concurrent claim held has reason locked. Without repos, { nothing: true } carries passedOver instead when ready pull requests did not go: per repo (lower case, ordered) the count of them. A ready pull request with a need that is not satisfied stays out of the train and goes back to waiting for needs; so does one whose item changed since it became ready (no longer approved or in progress, a new revision, or its repo removed), back to waiting for approval. A ready pull request whose item has an active lease (a lane still works on it, also with rework) stays ready and out of the train; expired leases end first. A group whose merge session is on another machine (or has none) is DOCKET_FORBIDDEN; an unknown group or one outside your targets is DOCKET_TARGET_UNKNOWN.

Tipo

escritura

Derecho

docket:merge:claim

Tipos de key

merge-session

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

merge.reconcile

POST /agent/tools/merge.reconcile

Before you merge, tell docket what GitHub shows for pull requests of your running merge train: per pull request (1 to 100) prId, draft, state ("open" or "closed"), merged, headSha and baseRef. A closed pull request becomes closed (merged: true makes it merged and checks its item) at once. An open one stays in the train; docket stores draft, head (a new head drops its review) and base branch, and the report weighs them: a pull request you skip and do not name in merge.report returns to the queue and is judged again (a draft waits with reason draft). A pull request that is no longer in the train (already closed or invalid) stays as it is. Returns { trainId, prs: [{ prId, status }] }. A prId that is not in the train is DOCKET_TRAIN_REPORT_MISMATCH pr-not-in-train and nothing is stored; a train of another key, a reported train or a lease that ran out is DOCKET_TRAIN_LEASE_ENDED; an unknown train is DOCKET_TRAIN_NOT_FOUND.

Tipo

escritura

Derecho

docket:merge:claim

Tipos de key

merge-session

Entrada

Salida

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

merge.renew

POST /agent/tools/merge.renew

Extend the lease of your running merge train by 60 minutes; call it every 20 minutes. A train of another key, a reported train or a lease that ran out is DOCKET_TRAIN_LEASE_ENDED; an unknown train is DOCKET_TRAIN_NOT_FOUND.

Tipo

escritura

Derecho

docket:merge:claim

Tipos de key

merge-session

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

merge.report

POST /agent/tools/merge.report

Report the result of your merge train: merged, conflict, culprit and dropped (each with a reason of up to 5000 characters) name pull requests of the train, each at most once; pull requests not named return to the queue; what merge.reconcile stored before the report (draft, head, base branch) counts there. If the item of a pull request changed since the claim (no longer approved or in progress, a new revision, or its repo removed), a pull request not named turns red and a merged one stays merged, both with end reason item-not-ready. releaseState is "released" (then package and version), "no-release" or "release-red". log is the tail of the run (up to 65 535 characters). After the train lease ended (until the train is reported) the key of the train still reports, if every pull request in merged is already merged on docket (GitHub webhook), otherwise DOCKET_TRAIN_REPORT_MISMATCH merged-not-on-github. The same report again (releaseState, package, version; log does not count) changes nothing and returns empty items; a different one is DOCKET_TRAIN_REPORT_MISMATCH report-differs. A report that does not fit the train is DOCKET_TRAIN_REPORT_MISMATCH; a train of another key is DOCKET_TRAIN_LEASE_ENDED. Nothing is stored in either case.

Tipo

escritura

Derecho

docket:merge:report

Tipos de key

merge-session

Entrada

Códigos de estado: 200 400 401 402 403 404 405 408 409 412 413 415 422 428 429 499 500 501 502 503 504

merge.sync

POST /agent/tools/merge.sync

Before you claim, bring docket in line with GitHub for pull requests a webhook delivery may have missed. Name the project groups (id or slug) like merge.claim and send prs (0 to 100, each repo and number once): repo, number, state ("open" or "closed"), merged, draft, headSha, branch, baseRef and body (up to 65 536 characters, null for none) as GitHub shows them now. docket books each like the webhook would, without a delivery, and writes only when something differs: a closed one becomes closed (merged: true makes it merged and checks its item); an open one gets its Docket line, draft, head (a new head drops its review), branch and base branch, and its readiness is weighed again. A pull request in a train stays as it is (status in train); one docket does not store or whose repo is not in the named groups gets status null and is not created. Returns { prs: [{ repo, number, status, changed }], held, heldTruncated }: held are the open pull requests of the groups that wait (not ready, in train, closed or merged), ordered by repo and number, up to 100, each with repo, number, status and reason (readiness reason, else invalid code, else end reason); heldTruncated is true when there are more. Call it with prs: [] first, read each held pull request on GitHub, then call it again with what you read. A group whose merge session is on another machine (or has none) is DOCKET_FORBIDDEN; an unknown group or one outside your targets is DOCKET_TARGET_UNKNOWN.

Tipo

escritura

Derecho

docket:merge:claim

Tipos de key

merge-session

Entrada