Workspace API reference

Workspace endpoints of the Quackback REST API: paths, parameters, request fields and responses.

JM
James Morton
Written By James MortonLast updated 3 days ago

This is the reference for the Workspace endpoints of the Quackback REST API: every endpoint, its parameters, request fields and response fields. It is generated from the API's OpenAPI description, so it matches what the API accepts.

All paths are relative to /api/v1 on your workspace's address (for example https://feedback.example.com/api/v1). Authenticate with an API key in the Authorization: Bearer qb_... header. For keys, errors, pagination and rate limits, see API overview. Every workspace also serves an interactive reference at /api/v1/docs.

Endpoints

  • GET /mentions/suggest: Suggest people to @-mention
  • GET /users/{principalId}/card: Get a mention hover card
  • GET /admin/usage: Get workspace usage counters
  • POST /setup: Set up a new workspace without the browser

Suggest people to @-mention

GET /api/v1/mentions/suggest

Typeahead for mentions, matching the start of the display name. An empty query returns the first page of people. Returns at most 10 results and never exposes email addresses. Authenticated by the signed-in session cookie, not an API key. Limited to 60 requests per minute per session.

Parameters

Name

In

Type

Required

Description

q

query

string

No

Start of the display name

scope

query

string (team)

No

Set to team to return teammates only

Response 200.

Get a mention hover card

GET /api/v1/users/{principalId}/card

Small profile payload for an @-mention chip: name, avatar, role and join date, with no email. Authenticated by the signed-in session cookie, not an API key.

Parameters

Name

In

Type

Required

Description

principalId

path

string

Yes

Principal ID

Response 200: returns principalId, displayName, avatarUrl, role, joinedAt.

Get workspace usage counters

GET /api/v1/admin/usage

Usage counters for external billing meters. Authenticated with the operator token set in the ADMIN_API_TOKEN environment variable, sent as a bearer token; API keys are not accepted. Responds 404 when that variable is not set.

Response 200: returns aiTokensThisMonth, postCount, boardCount, teamSeatCount, pendingInviteCount.

Set up a new workspace without the browser

POST /api/v1/setup

Creates the workspace and its first admin, and returns that admin's first API key, once. Authenticated with the setup token, sent as a bearer token: the SETUP_TOKEN environment variable, or the token the server writes to its log once on first boot. It exists only while the workspace has no admin; at any other time, and on hosted workspaces, it answers 404 without a trace. An existing account with that email is reused only if its address is verified (409 otherwise). API keys are not accepted. Limited to 10 requests per minute per address.

Request body

Field

Type

Required

Description

workspaceName

string

Yes

Name of the workspace

adminEmail

string

Yes

Email address of the first admin

adminName

string

Yes

Display name of the first admin

Response 201: returns workspace, admin, apiKey, reusedExistingAccount.

Was this helpful?

Your feedback shapes what we write next.

← Previous

Apps API reference

Next →

Approvals API reference

Related articles

API overviewCreate an API key, authenticate to the REST API, and learn the base URL, errors, pagination and rate limits. Full endpoint reference lives at /api/v1/docs.Users API referenceUsers endpoints of the Quackback REST API: paths, parameters, request fields and responses.Webhooks API referenceWebhooks endpoints of the Quackback REST API: paths, parameters, request fields and responses.Members API referenceMembers endpoints of the Quackback REST API: paths, parameters, request fields and responses.