Help › Reference
HTTP API reference
Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.
The routes of a Reqlyn server's own API that its web client uses, as the server describes them (/v1/api.json, reqlyn-server api describe). This page is written by the program from that description (reqlyn-server reference api), and a test fails when the two differ. A caller sends a service token or a session as a bearer token; how the API is used is in Using a server. The OpenAPI description of what a workspace has published, and the clients made from it, are another description, /v1/openapi.json.
GET /v1/activation-requests
The workspace's activation requests, waiting and decided.
Answers:
200: Each request.401: Refused: the error says why.
POST /v1/activation-requests/{id}/approve
Approves an activation request, activating the version: a publisher's, never whoever asked.
Answers:
200: Approved.403: Refused: the error says why.422: Refused: the error says why.
POST /v1/activation-requests/{id}/refuse
Refuses an activation request: a publisher's, never whoever asked.
Answers:
200: Refused.403: Refused: the error says why.422: Refused: the error says why.
GET /v1/activity
What happened in the workspace, newest first, held to what the caller may read: drafts saved, versions published, activations asked, decided and made, threads, drift found.
Answers:
200: A page of the activity.400: Refused: the error says why.
GET /v1/agents
The workspace's private agents, the environments each carries and when each was last heard from.
Answers:
200: Each agent.403: Refused: the error says why.
POST /v1/agents
Adds a private agent: its token is given once and cannot be read again. An administrator's.
Takes a NewAgent.
Answers:
201: Added, with its token.403: Refused: the error says why.409: Refused: the error says why.422: Refused: the error says why.
DELETE /v1/agents/{name}
Revokes an agent: its token is refused from now on.
Answers:
204: Revoked.403: Refused: the error says why.404: Refused: the error says why.
PUT /v1/agents/{name}/environments
Sets the environments an agent carries; the rest of the deployment stays as it is. An administrator's.
Takes a CarriedEnvironments.
Answers:
200: Each agent, as it now stands.403: Refused: the error says why.422: Refused: the error says why.
POST /v1/assistant/chats
Starts a chat with the assistant over the workspace's drafts. An editor's.
Answers:
200: The chat.401: Refused: the error says why.403: Refused: the error says why.
GET /v1/assistant/chats/{id}
One of the caller's chats.
Answers:
200: The chat.401: Refused: the error says why.404: Refused: the error says why.
POST /v1/assistant/chats/{id}/diagnose
Says a failed run's or a load run's record in a chat: the assistant says where it failed and proposes the fix, for the operation's draft or as a new load run started when kept.
Takes a DiagnoseRun.
Answers:
200: The chat, answered.401: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
POST /v1/assistant/chats/{id}/messages
Says something in a chat; the assistant reads and proposes, and its answer is in the chat.
Takes a SayToAssistant.
Answers:
200: The chat, answered.401: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
POST /v1/assistant/chats/{id}/proposals/{proposal}/keep
Keeps a proposal: the change is saved to its draft.
Answers:
200: The chat.401: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
POST /v1/assistant/chats/{id}/proposals/{proposal}/reject
Rejects a proposal: nothing is saved.
Answers:
200: The chat.401: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
GET /v1/audit
The workspace's audit trail, a page at a time. An administrator's.
Answers:
200: A page of the trail.400: Refused: the error says why.403: Refused: the error says why.
PUT /v1/comments/{id}
Changes a comment's text. Its author's alone.
Takes a WriteComment.
Answers:
200: The thread.400: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
DELETE /v1/comments/{id}
Removes a comment: it keeps its place, marked, without its text. Its author's alone.
Answers:
200: The thread.403: Refused: the error says why.404: Refused: the error says why.
POST /v1/demonstrations
Compares two or more recordings of one task, uploads of the caller's, and says what they show; with a draft id, saves the operation they draft as that new draft. Nothing is sent.
Takes a DemonstrationAsked.
Answers:
200: What they show.401: Refused: the error says why.403: Refused: the error says why.409: Refused: the error says why.422: Refused: the error says why.
GET /v1/drafts
The workspace's drafts, the latest saved first. An editor's.
Answers:
200: Each draft.401: Refused: the error says why.403: Refused: the error says why.
GET /v1/drafts/{id}
A draft: its operation, its requests as definition text, and its revision.
Answers:
200: The draft.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
PUT /v1/drafts/{id}
Saves a draft, made from the revision named, which the server must still hold; refused DRAFT_CONFLICT when someone saved since.
Takes a SaveDraft.
Answers:
200: Saved, at its new revision.401: Refused: the error says why.403: Refused: the error says why.409: Refused: the error says why.422: Refused: the error says why.
GET /v1/drafts/{id}/document
A draft's live document, its whole state as one Yjs v1 update: made from its latest revision the first time.
Answers:
200: The document.403: Refused: the error says why.404: Refused: the error says why.
POST /v1/drafts/{id}/document
Takes one change to a draft's live document, a Yjs v1 update; refused unless the document still holds a draft.
Answers:
204: Taken.403: Refused: the error says why.404: Refused: the error says why.413: Refused: the error says why.422: Refused: the error says why.
POST /v1/drafts/{id}/document/revision
Saves a draft's live document as it stands, everyone's edits, as the draft's next revision, through the same checks as any save.
Answers:
200: Saved, at its new revision.403: Refused: the error says why.404: Refused: the error says why.409: Refused: the error says why.422: Refused: the error says why.
POST /v1/drafts/{id}/document/since
What a copy of a draft's live document lacks, given the copy's Yjs state vector: one Yjs v1 update.
Answers:
200: What it lacks.403: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
GET /v1/drafts/{id}/document/stream
Says when a draft's live document changes, as server-sent events named changed, each a DocumentChanged (its count of changes and the draft's revision), at once and on each change.
Answers:
200: A stream of changed events.403: Refused: the error says why.404: Refused: the error says why.
GET /v1/drafts/{id}/forks
A draft's forks and where each stands, the newest first. An editor's.
Answers:
200: Each fork.401: Refused: the error says why.403: Refused: the error says why.
POST /v1/drafts/{id}/forks
Forks a draft: a draft of its own, made from this one as it is saved, that anyone who may edit drafts may change and propose back.
Answers:
200: The fork.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
GET /v1/drafts/{id}/review
What publishing the draft would do: what stops it, what changed since the latest version, what its callers would see, and what each environment does not bind.
Answers:
200: The review.403: Refused: the error says why.404: Refused: the error says why.
POST /v1/drafts/{id}/versions
Publishes the revision of the draft the publisher reviewed as the operation's next version, which never changes. A publisher's.
Takes a Publish.
Answers:
201: Published.403: Refused: the error says why.409: Refused: the error says why.422: Refused: the error says why.
GET /v1/environments
The workspace's environments.
Answers:
200: Each environment.401: Refused: the error says why.
GET /v1/environments/{name}
An environment at its latest revision: its variables and its credential bindings, which name secrets and never hold their values.
Answers:
200: The environment.404: Refused: the error says why.
PUT /v1/environments/{name}
Saves an environment as its next revision, made from the revision named. An administrator's.
Takes a SaveEnvironment.
Answers:
200: Saved.403: Refused: the error says why.409: Refused: the error says why.422: Refused: the error says why.
POST /v1/environments/{name}/credentials/{credential}/sign-in
Starts signing an environment's oauth_login credential in: the provider's page to send the browser to, which comes back to /v1/oauth/callback. An administrator's.
Answers:
200: Where to send the browser.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
POST /v1/flows
An operation as the canvas draws it: a node per step, the edges its order and actions make, and the workflows its steps were called from. Nothing is kept.
Takes a FlowAsked.
Answers:
200: Its flow.403: Refused: the error says why.422: Refused: the error says why.
GET /v1/forks
Every fork of the workspace's drafts and where each stands, the newest first. An editor's.
Answers:
200: Each fork.401: Refused: the error says why.403: Refused: the error says why.
POST /v1/forks/{fork}/decline
Declines a proposed fork; never by whoever proposed it.
Answers:
200: Declined.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
GET /v1/forks/{fork}/parts
How a fork differs from its draft as that draft is now, part by part: the inputs, the output, each step, each request.
Answers:
200: Its parts, against the draft's revision named.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
POST /v1/forks/{fork}/proposal
Offers an open fork back to the draft it was made from.
Answers:
200: Proposed.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
POST /v1/forks/{fork}/take
Takes a proposed fork into its draft, every part or those named, against the draft's revision they were read at; never by whoever proposed it.
Takes a TakeFork.
Answers:
200: Taken.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.409: Refused: the error says why.422: Refused: the error says why.
GET /v1/identity
Where people sign in.
Answers:
200: The identity provider.404: Refused: the error says why.
GET /v1/inventory
The workspace's API inventory: each description it registers or its operations carry, with its owner, lint score, users, coverage, drift and health.
Answers:
200: Each description, by name.401: Refused: the error says why.
POST /v1/inventory/descriptions
Registers a description by its address, as a file or by its path in the workspace's Git source. An editor's.
Takes a RegisterDescription.
Answers:
200: Registered.401: Refused: the error says why.403: Refused: the error says why.422: Refused: the error says why.
GET /v1/inventory/descriptions/{id}
One description of the inventory and what the rules find in it.
Answers:
200: The description.401: Refused: the error says why.404: Refused: the error says why.
DELETE /v1/inventory/descriptions/{id}
Removes a registered description from the inventory. An editor's.
Answers:
204: Removed.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
PUT /v1/inventory/descriptions/{id}/owner
Names who answers for a registered description; empty to go by what it says. An editor's.
Takes a SetDescriptionOwner.
Answers:
200: Its owner set.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
POST /v1/inventory/descriptions/{id}/read
Reads a description registered by its address again, now. An editor's.
Answers:
200: As read, or why it was not.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
GET /v1/inventory/settings
How often descriptions by address are read again, and the days health is measured over.
Answers:
200: The settings.401: Refused: the error says why.
PUT /v1/inventory/settings
Sets them. An administrator's.
Takes a InventorySettings.
Answers:
200: Set.401: Refused: the error says why.403: Refused: the error says why.422: Refused: the error says why.
GET /v1/inventory/traffic
The traffic the workspace's descriptions do not account for over its window: undocumented endpoints on the hosts they name, and hosts none names.
Answers:
200: What was found.401: Refused: the error says why.
GET /v1/loads
The workspace's load runs the caller reaches, newest first, at most fifty.
Answers:
200: The load runs.401: Refused: the error says why.
GET /v1/loads/{id}
One load run: its profile, where it stands, and what came of it.
Answers:
200: The load run.401: Refused: the error says why.404: Refused: the error says why.
GET /v1/me/notices
What the person signed in is emailed of, and the address their identity provider gives, the only one mail goes to.
Answers:
200: Their choice.401: Refused: the error says why.
PUT /v1/me/notices
Chooses what the person signed in is emailed of, at the address their identity provider gives.
Takes a SetMyNotices.
Answers:
200: Their choice, as it now stands.401: Refused: the error says why.422: Refused: the error says why.
DELETE /v1/me/notices
Emails the person signed in nothing.
Answers:
204: Stopped.401: Refused: the error says why.
GET /v1/me/sign-ins
The sign-ins the signed-in person makes with their own account: each environment's per_person credential, and when they signed it in.
Answers:
200: Each sign-in.401: Refused: the error says why.
GET /v1/members
The people with a role in the workspace.
Answers:
200: Each member.403: Refused: the error says why.
PUT /v1/members/{subject}
Gives a person a role, by the identity provider's identifier of them. An administrator's.
Takes a GrantRole.
Answers:
200: Given.403: Refused: the error says why.409: Refused: the error says why.422: Refused: the error says why.
DELETE /v1/members/{subject}
Takes a person's role away; the last administrator keeps theirs.
Answers:
204: Removed.403: Refused: the error says why.404: Refused: the error says why.409: Refused: the error says why.
GET /v1/notifications/channels
The workspace's Slack and Teams channels: the secret that holds each one's webhook address, never the address, and what each is told of. An administrator's.
Answers:
200: Each channel.403: Refused: the error says why.
PUT /v1/notifications/channels/{channel}
Sets a channel, slack or teams: the secret whose value is its incoming webhook's address, and what it is told of. An administrator's.
Takes a SaveNotifyChannel.
Answers:
200: Each channel, as it now stands.403: Refused: the error says why.422: Refused: the error says why.
DELETE /v1/notifications/channels/{channel}
Stops telling a channel anything. Its secret stays.
Answers:
204: Removed.403: Refused: the error says why.404: Refused: the error says why.
GET /v1/notifications/deliveries
What became of the latest hundred deliveries to the workspace's channels. An administrator's.
Answers:
200: Each delivery, the latest first.403: Refused: the error says why.
GET /v1/operations
The catalog: each published operation of the workspace at its latest version.
Answers:
200: A page of the catalog.400: Refused: the error says why.401: Refused: the error says why.
GET /v1/operations/{id}/versions/{version}/activations
Where a version is activated.
Answers:
200: Each environment it runs in.404: Refused: the error says why.
PUT /v1/operations/{id}/versions/{version}/activations/{environment}
Activates a version in an environment once its bindings and cases hold; where the deployment asks for approval, asks a second person instead. A publisher's.
Answers:
200: Activated.202: Asked: it waits for a second person.403: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
GET /v1/operations/{id}/versions/{version}/changes
What changed in a version since an earlier one: each check a caller of the earlier one depends on, and each change by its area.
Answers:
200: The comparison.401: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
GET /v1/operations/{id}/versions/{version}/entry
One version of an operation, as the catalog lists it.
Answers:
200: The version.401: Refused: the error says why.404: Refused: the error says why.
GET /v1/operations/{id}/versions/{version}/portal
One version as its portal page shows it: its entry, limits, errors, examples from its regression cases and a snippet in each language.
Answers:
200: The page.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
PUT /v1/operations/{id}/versions/{version}/public
Shows the version in the workspace's public portal, read without signing in. An administrator's; audited.
Answers:
204: Public.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
DELETE /v1/operations/{id}/versions/{version}/public
Takes the version out of the workspace's public portal. An administrator's; audited.
Answers:
204: No longer public.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
POST /v1/operations/{id}/versions/{version}/runs
Asks for a run of a version in an environment.
Takes a SubmitRun.
Answers:
200: Over already, or asked for before with the same key.202: Accepted, not yet over.400: Refused: the error says why.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.409: Refused: the error says why.422: Refused: the error says why.429: Refused: the error says why.
GET /v1/portal/counts
How the portal was read: views and searches per page per day, counts only. An administrator's.
Answers:
200: Newest day first.401: Refused: the error says why.403: Refused: the error says why.422: Refused: the error says why.
GET /v1/portal/settings
The workspace's portal: the domain only it answers on, its title, look and accent.
Answers:
200: Its settings.401: Refused: the error says why.
PUT /v1/portal/settings
Sets the portal's domain, title, look and accent. A domain is a name, not the server's own address nor another workspace's. An administrator's; audited.
Takes a PortalSettings.
Answers:
200: What was kept.401: Refused: the error says why.403: Refused: the error says why.422: Refused: the error says why.
GET /v1/presence
Who has a draft or a version open now, each once, and whether they are editing it.
Answers:
200: Who is there.400: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
PUT /v1/presence
Says this window has the thing open, and whether it is editing: again every few seconds while it has. One not heard from for 45 seconds is gone.
Takes a Announce.
Answers:
200: Who is there now.400: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
DELETE /v1/presence
Says this window has closed the thing.
Answers:
204: Gone.
GET /v1/presence/stream
Who has the thing open, as server-sent events named presence: at once, then on every change.
Answers:
200: A stream of presence events, each a Presence.403: Refused: the error says why.404: Refused: the error says why.
GET /v1/public/{workspace}/portal
The versions a workspace shows publicly. Read without signing in.
Answers:
200: Its public versions.404: Refused: the error says why.
GET /v1/public/{workspace}/portal/{id}/{version}
A public version's page, made from its schemas. Read without signing in.
Answers:
200: The page.404: Refused: the error says why.
POST /v1/request-definitions
A request as written, as the definition text a draft keeps. Nothing is kept or sent.
Takes a DefineRequest.
Answers:
200: Its definition.403: Refused: the error says why.422: Refused: the error says why.
POST /v1/request-definitions/read
A draft's request read from its definition text into the form it is written in.
Takes a RequestDefinition.
Answers:
200: As written.403: Refused: the error says why.422: Refused: the error says why.
GET /v1/requests
The caller's history of requests written in the browser, newest first.
Answers:
200: A page of the history.400: Refused: the error says why.401: Refused: the error says why.
POST /v1/requests/send
Sends a request the caller wrote, in an environment: its variables filled, a credential added for an operator or above. The answer is kept as the caller's, masked.
Takes a SendRequest.
Answers:
200: Sent and answered, or not sent and why.400: Refused: the error says why.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
GET /v1/requests/{id}
A request the caller sent, as it is kept.
Answers:
200: The send.401: Refused: the error says why.404: Refused: the error says why.
GET /v1/runs
The workspace's runs, newest first.
Answers:
200: A page of runs.400: Refused: the error says why.401: Refused: the error says why.
GET /v1/runs/{id}
A run: how it stands, and once it is over its output or why there is none, and its steps.
Answers:
200: The run.401: Refused: the error says why.404: Refused: the error says why.
GET /v1/runs/{id}/events
What a run did, in order, after an event already read.
Answers:
200: Its events, and how it stands.401: Refused: the error says why.404: Refused: the error says why.
GET /v1/secrets/{id}
What is known of a secret: its revision and when it was set. Never its value.
Answers:
200: The secret.403: Refused: the error says why.404: Refused: the error says why.
PUT /v1/secrets/{id}
Sets a secret's value. It is never read back. An administrator's.
Takes a SetSecret.
Answers:
200: Set.403: Refused: the error says why.422: Refused: the error says why.
GET /v1/shared-requests
The requests shared in the workspace, by folder and name (Usability, U10). Anyone with a role reads them; a token limited to named operations has none.
Answers:
200: Each shared request.401: Refused: the error says why.
PUT /v1/shared-requests/{id}
Saves a shared request, new without based_on_revision, else over that revision, which the server must still hold; refused DRAFT_CONFLICT when someone saved since. An editor's. Kept as definition text: a credential is named, a secret value is not kept.
Takes a SaveSharedRequest.
Answers:
200: Saved, at its new revision.401: Refused: the error says why.403: Refused: the error says why.409: Refused: the error says why.422: Refused: the error says why.
DELETE /v1/shared-requests/{id}
Removes a shared request. An editor's.
Answers:
204: Removed.401: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
GET /v1/shares
The sessions shared now, of operations the caller reaches, the latest first.
Answers:
200: Each live session.
POST /v1/shares
Shares a session (a test as it runs): followers read what its owner's client tells it.
Takes a NewShare.
Answers:
201: Shared.404: Refused: the error says why.422: Refused: the error says why.
GET /v1/shares/{id}
A shared session.
Answers:
200: The session.404: Refused: the error says why.
PUT /v1/shares/{id}/end
Ends a session: it is no longer live and takes no more. Its owner's alone.
Answers:
204: Ended.403: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
POST /v1/shares/{id}/events
Tells a session what happened in it: one event of the masked trace. Its owner's alone.
Takes a Told.
Answers:
204: Told.403: Refused: the error says why.404: Refused: the error says why.422: Refused: the error says why.
GET /v1/shares/{id}/stream
Follows a session as server-sent events: each event named told (a ShareEvent) in order from ?after=, then ended once its owner ends it.
Answers:
200: A stream of told events, then ended.404: Refused: the error says why.
GET /v1/threads
Every thread on a draft, a version or a run, its steps' and drift findings' among them, the first opened first.
Answers:
200: Each thread with its comments.400: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
POST /v1/threads
Opens a thread with its first comment, on what the caller may read. A member mentioned as @<identifier> is named in it.
Takes a OpenThread.
Answers:
201: Opened.400: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
GET /v1/threads/{id}
One thread and its comments.
Answers:
200: The thread.403: Refused: the error says why.404: Refused: the error says why.
POST /v1/threads/{id}/comments
Adds a comment to a thread.
Takes a WriteComment.
Answers:
201: The thread with it.400: Refused: the error says why.403: Refused: the error says why.404: Refused: the error says why.
PUT /v1/threads/{id}/resolution
Resolves a thread, or opens it again: the person who opened it, or someone who may edit.
Takes a ResolveThread.
Answers:
200: The thread.403: Refused: the error says why.404: Refused: the error says why.
POST /v1/uploads
Keeps a file of the caller's for a while: an input of a run, or a recording to compare. Sealed, and gone when it expires.
Answers:
201: Kept.401: Refused: the error says why.403: Refused: the error says why.413: Refused: the error says why.
GET /v1/web/session
The browser's session, and the CSRF token its writes carry.
Answers:
200: Signed in.401: Refused: the error says why.
POST /v1/web/session/renew
Renews the browser's session while it is used, by the identity provider's refresh token kept for it; refused when there is none or the provider will not.
Answers:
200: Renewed: the session and how long it lasts now.401: Refused: the error says why.403: Refused: the error says why.
GET /v1/web/sign-in
Sends the browser to the identity provider; it comes back signed in, or to /?sign_in=<code> saying why not.
Answers:
302: To the identity provider.404: Refused: the error says why.
POST /v1/web/sign-out
Ends the browser's session.
Answers:
204: Signed out.401: Refused: the error says why.403: Refused: the error says why.
Help for Reqlyn 0.5.1. All help topics