KnownScopeRequest a walkthrough

API

Every endpoint, published in full.

KnownScope is API first. The first-party interface is built on this description and nothing else, so publishing it costs us nothing and saves you a call. Read it at 2am if you want to.

The document

OpenAPI 0.5.0

54 paths, 75 operations. The server's request and response types and its routing interfaces are generated from this file, and the build fails if they drift.

Download openapi.yaml

  • Every endpoint checks Campaign access on the server. Nothing in this document is a client-side permission.
  • Writes use optimistic concurrency. A stale If-Match is rejected rather than applied, which is why two people editing one row cannot silently overwrite each other.
  • Bulk operations return a result per item, and retries with the same idempotency key do not double-apply.
  • This describes the current build. Capabilities on the rest of this site that are not in here have not shipped yet.

Endpoints by area

Operations

  • GET/healthzCheck process liveness
  • GET/readyzCheck traffic readiness
  • GET/metricsRead process metrics

System

  • GET/api/v1/system/infoRead public application metadata

Authentication

  • GET/api/v1/auth/methodsDiscover configured browser sign-in methods
  • GET/api/v1/auth/loginBegin the configured OIDC authorization-code flow
  • GET/api/v1/auth/callbackComplete the configured OIDC authorization-code flow
  • POST/api/v1/auth/break-glassAuthenticate the installation recovery administrator
  • POST/api/v1/auth/logoutRevoke the current browser session

Session

  • GET/api/v1/sessionRead the current authenticated session

Directory

  • GET/api/v1/usersList active users in the current tenant directory
  • GET/api/v1/groupsList active groups in the current tenant
  • POST/api/v1/groupsCreate a tenant group
  • GET/api/v1/groups/{groupId}/membersList the active members of a tenant group
  • PUT/api/v1/groups/{groupId}/members/{userId}Add a user to a tenant group
  • DELETE/api/v1/groups/{groupId}/members/{userId}Remove a user from a tenant group
  • GET/api/v1/campaign-templatesList active Campaign templates
  • POST/api/v1/campaign-templatesCreate and publish the first immutable Campaign template version
  • GET/api/v1/campaign-templates/{templateId}/versionsList immutable versions of a Campaign template
  • POST/api/v1/campaign-templates/{templateId}/versionsPublish the next immutable Campaign template version
  • GET/api/v1/global-role-assignmentsList additive tenant-wide Campaign grants
  • POST/api/v1/global-role-assignmentsAssign or change an additive tenant-wide Campaign role
  • DELETE/api/v1/global-role-assignments/{assignmentId}Remove an additive tenant-wide Campaign role

Tag Catalog

  • GET/api/v1/tag-namespacesList tenant tag namespaces and active or retired tags
  • POST/api/v1/tag-namespacesCreate a governed tag namespace
  • PATCH/api/v1/tag-namespaces/{namespaceId}Edit a tag namespace label or help text
  • POST/api/v1/tag-namespaces/{namespaceId}/tagsCreate a stable tag in a namespace
  • PATCH/api/v1/controlled-tags/{tagId}Edit or retire a stable controlled tag

Campaigns

  • GET/api/v1/campaignsList Campaigns visible to the current user
  • POST/api/v1/campaignsCreate a Draft Campaign from a template snapshot
  • GET/api/v1/campaigns/{campaignId}Read one permitted Campaign
  • PATCH/api/v1/campaigns/{campaignId}Update Campaign metadata or lifecycle
  • GET/api/v1/campaigns/{campaignId}/membersList the Owner and direct user/group Campaign memberships
  • POST/api/v1/campaigns/{campaignId}/membersAdd a user/group or change its direct Campaign role
  • DELETE/api/v1/campaigns/{campaignId}/members/{membershipId}Remove a direct user/group Campaign membership
  • POST/api/v1/campaigns/{campaignId}/owner-transferTransfer primary ownership and retain the former Owner as a Worker

Campaign Fields

  • GET/api/v1/campaigns/{campaignId}/fieldsList Field Definitions for a Campaign schema version
  • POST/api/v1/campaigns/{campaignId}/fieldsAdd an optional Field Definition to a Campaign
  • GET/api/v1/campaigns/{campaignId}/schema-proposalsList schema proposals and their decisions
  • POST/api/v1/campaigns/{campaignId}/schema-proposalsPropose an optional Field Definition
  • POST/api/v1/campaigns/{campaignId}/schema-proposals/{proposalId}/decisionApprove or reject a schema proposal
  • GET/api/v1/campaigns/{campaignId}/schema-draftGet the caller's active Campaign schema draft
  • PUT/api/v1/campaigns/{campaignId}/schema-draftCreate or update the caller's active Campaign schema draft
  • POST/api/v1/campaigns/{campaignId}/schema-drafts/{draftId}/submitSubmit a persisted schema draft for Owner review
  • POST/api/v1/campaigns/{campaignId}/schema-drafts/{draftId}/publishPublish an Owner's complete schema draft atomically

Campaign Items

  • GET/api/v1/campaigns/{campaignId}/itemsList active Campaign Items
  • POST/api/v1/campaigns/{campaignId}/itemsAdd a Campaign Item
  • POST/api/v1/campaigns/{campaignId}/items/bulk-updateApply one retry-safe update to a bounded Item selection
  • POST/api/v1/campaigns/{campaignId}/items/bulk-archiveRemove a bounded Item selection from the active working set
  • GET/api/v1/campaigns/{campaignId}/item-viewsList visible personal and team Item-grid views
  • POST/api/v1/campaigns/{campaignId}/item-viewsSave a personal or Owner-managed team Item-grid view
  • PUT/api/v1/campaigns/{campaignId}/item-views/{viewId}Replace a visible saved Item-grid view
  • DELETE/api/v1/campaigns/{campaignId}/item-views/{viewId}Delete a personal or Owner-managed team Item-grid view
  • GET/api/v1/campaigns/{campaignId}/items/{itemId}Read one Campaign Item
  • PUT/api/v1/campaigns/{campaignId}/items/{itemId}Replace the dynamic values of a Campaign Item
  • DELETE/api/v1/campaigns/{campaignId}/items/{itemId}Remove a Campaign Item from the active working set

Campaign Exports

  • POST/api/v1/campaigns/{campaignId}/exportsDownload a bounded, permission-aware Campaign Item export

Collaboration

  • GET/api/v1/campaigns/{campaignId}/activityList material Campaign changes and work updates in one chronological stream
  • GET/api/v1/campaigns/{campaignId}/work-log/participantsList active people who may be mentioned in this Campaign
  • GET/api/v1/campaigns/{campaignId}/work-updatesList Campaign work updates, optionally narrowed to one Item
  • POST/api/v1/campaigns/{campaignId}/work-updatesAdd a Campaign- or Item-scoped work update
  • POST/api/v1/campaigns/{campaignId}/work-updates/bulkAppend one retry-safe work update to each selected Item
  • PATCH/api/v1/campaigns/{campaignId}/work-updates/{workUpdateId}Append a corrected revision to the work update authored by the caller
  • DELETE/api/v1/campaigns/{campaignId}/work-updates/{workUpdateId}Replace a work update with a retained soft-delete tombstone
  • GET/api/v1/campaigns/{campaignId}/work-updates/{workUpdateId}/revisionsList immutable revisions for one permitted work update

Campaign Imports

  • GET/api/v1/campaigns/{campaignId}/importsList recent governed imports for a Campaign
  • POST/api/v1/campaigns/{campaignId}/importsUpload and safely inspect one CSV, XLSX, or clipboard source
  • GET/api/v1/campaigns/{campaignId}/imports/{importId}Read import state, reviewed summary, and bounded outcomes
  • DELETE/api/v1/campaigns/{campaignId}/imports/{importId}Cancel an uncommitted import and erase its staged source
  • POST/api/v1/campaigns/{campaignId}/imports/{importId}/previewSelect worksheet, header, encoding, delimiter, and data rows
  • POST/api/v1/campaigns/{campaignId}/imports/{importId}/dry-runValidate every selected row and classify intended writes
  • POST/api/v1/campaigns/{campaignId}/imports/{importId}/commitQueue the exact reviewed import plan for idempotent commit
  • GET/api/v1/campaigns/{campaignId}/imports/{importId}/errors.csvDownload a permission-checked, formula-safe row error report

Audit

  • GET/api/v1/campaigns/{campaignId}/audit-eventsList the permitted Campaign audit timeline
  • GET/api/v1/campaigns/{campaignId}/audit-events/{auditEventId}Inspect the permission-filtered values captured by one Campaign audit event

Next step

Read it, then tell us what is missing.

If an endpoint you need is not in there, that is a useful thing for us to hear before the preview closes.

Request a walkthroughSee it working