API reference
Want to automate ProcesOS or connect another tool? This page lists the operations this instance offers to outside callers, and who may call each one.
It describes this instance at version 3.21.0.
- Base URL
https://procesos.techreform.de
OpenAPI document (JSON) Open it in the API client you already use. Your credentials stay on your own machine.
Authentication
The API knows three credentials. Each operation below says which of them it accepts.
Session cookie
Your browser sends it while you are signed in to this instance. A call from this browser needs nothing else.
Session token
For the companion app. A signed-in person asks POST /api/user/session-token for a token and sends it as a bearer token. It acts as that person.
Authorization: Bearer <session-token>API key
For scripts and other tools. A personal key acts as you. A key bound to a workspace acts for that workspace only.
Authorization: Bearer <api-key>x-api-key: <api-key>No API key reaches the admin API or creates keys and session tokens. A key bound to a workspace reaches neither your personal routes nor any other workspace.
Operations
Credentials /api/credentials
GET /api/credentials/verify/{token} Verifies a shared credential by its verification token, for anyone it was shown to.
Who may call it
- The token in the path is the authority. No sign-in needed.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
token | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
Dashboard /api/dashboard
GET /api/dashboard The signed-in person's dashboard: responsibilities, open tasks and recent activity.
Who may call it
- Signed-in person, by session cookie or session token.
- Checks that the person is a confirmed member of the workspace.
- A personal API key reaches it and acts as its owner. A key bound to a workspace does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
space | Query | string | optional |
Documented at access level: who may call it, not yet what it answers.
Diagrams /api/diagrams
GET /api/diagrams/{id} One process diagram with its BPMN XML and metadata, if the caller may view it.
Who may call it
- Signed-in person, by session cookie or session token.
- Asks about these workspace permissions:
diagrams:editdiagrams:viewgtt:manage - A personal API key reaches it and acts as its owner. A key bound to a workspace reaches it, and the operation holds it to that workspace. A key limited to a scope does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
POST /api/diagrams/{id}/narration Generates a plain-language narration of a process diagram.
Who may call it
- Signed-in person, by session cookie or session token.
- Asks about these workspace permissions:
diagrams:view - A personal API key reaches it and acts as its owner. A key bound to a workspace reaches it, and the operation holds it to that workspace. A key limited to a scope does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
Marketplace /api/marketplace
GET /api/marketplace/listings Lists marketplace listings, filtered by the facets in the query.
Who may call it
- Signed-in person, by session cookie or session token.
- Checks that the person is a confirmed member of the workspace.
- A personal API key reaches it and acts as its owner. A key bound to a workspace reaches it, and the operation holds it to that workspace. A key limited to a scope does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
creatorSpaceId | Query | string | optional |
itemType | Query | string | optional |
limit | Query | string | optional |
nearLat | Query | string | optional |
nearLng | Query | string | optional |
questCounts | Query | string | optional |
questGroup | Query | string | optional |
radiusKm | Query | string | optional |
skip | Query | string | optional |
sort | Query | string | optional |
Documented at access level: who may call it, not yet what it answers.
POST /api/marketplace/listings/{id}/evidence/files Uploads a photo or PDF as quest evidence and answers the reference to cite.
Who may call it
- Signed-in person, by session cookie or session token.
- A personal API key reaches it and acts as its owner. A key bound to a workspace reaches it. A key limited to a scope does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
GET /api/marketplace/listings/{id}/runs Lists the passes of a quest's run lane.
Who may call it
- Signed-in person, by session cookie or session token.
- A personal API key reaches it and acts as its owner. A key bound to a workspace reaches it. A key limited to a scope does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
POST /api/marketplace/listings/{id}/runs Starts the caller's own pass through a quest's run lane.
Who may call it
- Signed-in person, by session cookie or session token.
- A personal API key reaches it and acts as its owner. A key bound to a workspace reaches it. A key limited to a scope does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
Notifications /api/notifications
GET /api/notifications The signed-in person's notifications, newest first, with unread counts.
Who may call it
- Signed-in person, by session cookie or session token.
- A personal API key reaches it and acts as its owner. A key bound to a workspace does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
limit | Query | string | optional |
unreadOnly | Query | string | optional |
Documented at access level: who may call it, not yet what it answers.
personal /api/personal
GET /api/personal/credential-assertions The credentials the signed-in person confirmed about themselves, and how each is known.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Documented at access level: who may call it, not yet what it answers.
Pricing /api/pricing
GET /api/pricing The public price list of this instance as data.
Who may call it
- Public: no sign-in needed.
Documented at access level: who may call it, not yet what it answers.
GET /api/pricing/founding-slots How many founding seats are left, per workspace type.
Who may call it
- Public: no sign-in needed.
Documented at access level: who may call it, not yet what it answers.
Workspaces /api/spaces
GET /api/spaces Lists the workspaces the signed-in person belongs to.
Who may call it
- Signed-in person, by session cookie or session token.
- Checks that the person is a confirmed member of the workspace.
- A personal API key reaches it and acts as its owner. A key bound to a workspace reaches it, and the operation holds it to that workspace. A key limited to a scope does not reach it.
Documented at access level: who may call it, not yet what it answers.
POST /api/spaces/{id}/academy/courses/{slug}/enroll Enrols the caller in a course of this workspace.
Who may call it
- Signed-in person, by session cookie or session token.
- Checks that the person is a confirmed member of the workspace.
- A personal API key reaches it and acts as its owner. A key bound to a workspace reaches it for that workspace only. A key limited to a scope does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
slug | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
GET /api/spaces/{id}/capabilities/domain-progress A person's progress in this workspace, grouped by life domain.
Who may call it
- Signed-in person, by session cookie or session token.
- A personal API key reaches it and acts as its owner. A key bound to a workspace reaches it for that workspace only. A key limited to a scope does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
GET /api/spaces/{id}/cmdb Lists the IT systems recorded in this workspace's CMDB.
Who may call it
- Signed-in person, by session cookie or session token.
- Asks about these workspace permissions:
graph:view - A personal API key reaches it and acts as its owner.
A key bound to a workspace reaches it for that workspace only. Scoped keys that reach it:
read_only
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
includeDrafts | Query | string | optional |
Documented at access level: who may call it, not yet what it answers.
GET /api/spaces/{id}/credentials Lists the credentials issued in this workspace, filtered by person, type or status.
Who may call it
- Signed-in person, by session cookie or session token.
- Asks about these workspace permissions:
members:view - A personal API key reaches it and acts as its owner.
A key bound to a workspace reaches it for that workspace only. Scoped keys that reach it:
read_only
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
status | Query | string | optional |
type | Query | string | optional |
userId | Query | string | optional |
Documented at access level: who may call it, not yet what it answers.
POST /api/spaces/{id}/hiop/ingest Ingests hiop.io metrics into this workspace, idempotent per delivery id.
Who may call it
- Signed-in person, by session cookie or session token.
- Asks about these workspace permissions:
hiop:manage - A personal API key reaches it and acts as its owner.
A key bound to a workspace reaches it for that workspace only. Scoped keys that reach it:
hiop_ingest
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
GET /api/spaces/{id}/members Lists the members of this workspace with their roles.
Who may call it
- Signed-in person, by session cookie or session token.
- Checks that the person is a confirmed member of the workspace.
- Asks about these workspace permissions:
members:changeRolemembers:invitemembers:kickmembers:viewroles:managespace:manage - A personal API key reaches it and acts as its owner. A key bound to a workspace reaches it for that workspace only. A key limited to a scope does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
GET /api/spaces/{id}/roles Lists the roles of this workspace with their permissions.
Who may call it
- Signed-in person, by session cookie or session token.
- Asks about these workspace permissions:
members:view - A personal API key reaches it and acts as its owner.
A key bound to a workspace reaches it for that workspace only. Scoped keys that reach it:
read_only
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
User /api/user
GET /api/user The signed-in person's own profile and resolved permissions.
Who may call it
- Signed-in person, by session cookie or session token.
- Checks that the person is a confirmed member of the workspace.
- A personal API key reaches it and acts as its owner. A key bound to a workspace does not reach it.
Documented at access level: who may call it, not yet what it answers.
GET /api/user/api-keys Lists the signed-in person's API keys, never their secrets.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Documented at access level: who may call it, not yet what it answers.
POST /api/user/api-keys Creates an API key for the signed-in person, optionally bound to a workspace.
Who may call it
- Signed-in person, by session cookie or session token.
- Asks the person to confirm their identity again first (step-up).
- Checks that the person is a confirmed member of the workspace.
- No API key reaches it.
Documented at access level: who may call it, not yet what it answers.
DELETE /api/user/api-keys Deletes one of the signed-in person's API keys.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Documented at access level: who may call it, not yet what it answers.
GET /api/user/commitment-check/courses/{courseId} Whether a course would take the signed-in person now, without enrolling them.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
courseId | Path | string | required |
locale | Query | string | optional |
Documented at access level: who may call it, not yet what it answers.
GET /api/user/commitment-check/listings/{listingId} Whether a quest would take the signed-in person now, without starting it.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
listingId | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
GET /api/user/core-chain The signed-in person's three-node core capability chain, read only.
Who may call it
- Signed-in person, by session cookie or session token.
- A personal API key reaches it and acts as its owner. A key bound to a workspace does not reach it.
Documented at access level: who may call it, not yet what it answers.
GET /api/user/credentials The credentials the signed-in person has earned, across all workspaces.
Who may call it
- Signed-in person, by session cookie or session token.
- A personal API key reaches it and acts as its owner. A key bound to a workspace does not reach it.
Documented at access level: who may call it, not yet what it answers.
PUT /api/user/devices Registers this device of the signed-in person for push notifications.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Documented at access level: who may call it, not yet what it answers.
DELETE /api/user/devices/{registrationId} Removes a push registration of the signed-in person.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
registrationId | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
GET /api/user/first-quest The signed-in person's first quest and how far they are through it.
Who may call it
- Signed-in person, by session cookie or session token.
- A personal API key reaches it and acts as its owner. A key bound to a workspace does not reach it.
Documented at access level: who may call it, not yet what it answers.
GET /api/user/goals The signed-in person's private goals, by state, with their revisions on request.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
include | Query | string | optional |
state | Query | string | optional |
Documented at access level: who may call it, not yet what it answers.
POST /api/user/goals Notes a private goal for the signed-in person, or forks one of their own.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Documented at access level: who may call it, not yet what it answers.
GET /api/user/goals/{id} One private goal of the signed-in person, with its revisions on request.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
include | Query | string | optional |
Documented at access level: who may call it, not yet what it answers.
PATCH /api/user/goals/{id} Edits, pauses, resumes or retires one private goal of the signed-in person.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
DELETE /api/user/goals/{id} Deletes one private goal of the signed-in person with all its revisions.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
POST /api/user/goals/{id}/milestones Adds a milestone to one private goal of the signed-in person.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
PATCH /api/user/goals/{id}/milestones/{milestoneId} Edits a milestone of a private goal, or marks it done or open.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
milestoneId | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
DELETE /api/user/goals/{id}/milestones/{milestoneId} Removes a milestone from a private goal of the signed-in person.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
milestoneId | Path | string | required |
baseVersion | Query | string | optional |
Documented at access level: who may call it, not yet what it answers.
GET /api/user/passes The signed-in person's passes through quest run lanes, newest first.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Documented at access level: who may call it, not yet what it answers.
GET /api/user/personal-space The id of the signed-in person's personal workspace.
Who may call it
- Signed-in person, by session cookie or session token.
- A personal API key reaches it and acts as its owner. A key bound to a workspace does not reach it.
Documented at access level: who may call it, not yet what it answers.
GET /api/user/quests The signed-in person's quests, grouped as the assignments page shows them.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
space | Query | string | optional |
Documented at access level: who may call it, not yet what it answers.
POST /api/user/session-token Hands the cookie session out as a bearer session token for the companion app.
Who may call it
- Signed-in person, by session cookie only. A session token is refused.
- No API key reaches it.
Documented at access level: who may call it, not yet what it answers.
GET /api/user/sessions Lists the signed-in person's sessions, after a fresh step-up proof.
Who may call it
- Signed-in person, by session cookie or session token.
- Asks the person to confirm their identity again first (step-up).
- A personal API key reaches it and acts as its owner. A key bound to a workspace does not reach it.
Documented at access level: who may call it, not yet what it answers.
DELETE /api/user/sessions Signs out every other session of the signed-in person, after a step-up proof.
Who may call it
- Signed-in person, by session cookie or session token.
- Asks the person to confirm their identity again first (step-up).
- A personal API key reaches it and acts as its owner. A key bound to a workspace does not reach it.
Documented at access level: who may call it, not yet what it answers.
DELETE /api/user/sessions/{id} Signs out one session of the signed-in person, after a step-up proof.
Who may call it
- Signed-in person, by session cookie or session token.
- Asks the person to confirm their identity again first (step-up).
- A personal API key reaches it and acts as its owner. A key bound to a workspace does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
id | Path | string | required |
Documented at access level: who may call it, not yet what it answers.
POST /api/user/step-up Proves the signed-in person again before a sensitive action.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Documented at access level: who may call it, not yet what it answers.
POST /api/user/step-up/email-code Sends a one-time code by e-mail for a step-up proof.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Documented at access level: who may call it, not yet what it answers.
GET /api/user/step-up/methods The step-up methods the signed-in person can use.
Who may call it
- Signed-in person, by session cookie or session token.
- No API key reaches it.
Documented at access level: who may call it, not yet what it answers.
GET /api/user/xp The signed-in person's XP profile: level, tier and skill breakdown.
Who may call it
- Signed-in person, by session cookie or session token.
- Checks that the person is a confirmed member of the workspace.
- A personal API key reaches it and acts as its owner. A key bound to a workspace does not reach it.
Documented at access level: who may call it, not yet what it answers.
Wizzy /api/wizard
GET /api/wizard/readiness Whether the AI assistant can answer in a workspace, and if not, why.
Who may call it
- Signed-in person, by session cookie or session token.
- A personal API key reaches it and acts as its owner. A key bound to a workspace reaches it, and the operation holds it to that workspace. A key limited to a scope does not reach it.
Parameters
| Name | Where | Type | required |
|---|---|---|---|
spaceId | Query | string | optional |
Documented at access level: who may call it, not yet what it answers.