Skip to main content
Webentor Studio

Help · API reference

Teams

Teams (called accounts in paths): members, invitations, projects and the audit log.

All groups

Get an accountGET /api/v1/accounts/{account}

Returns one team the caller belongs to: its id, slug, name, type and plan, and the caller's role in it. Any member may read it.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)

200 Success.

What comes back
  • account object, required
    • id string, required
    • slug string, required
    • name string, required
    • type string, required
    • plan string, required
  • role string, required: The caller’s role in the team.
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • default Any other failure, as RFC 9457 problem details.

List account assignmentsGET /api/v1/accounts/{account}/assignments

Lists which members are assigned to which of the team's projects, as user and project ids with the role on each, for the whole team in one unpaged data list. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

List account audit eventsGET /api/v1/accounts/{account}/audit-events

Returns the team's audit log, newest first, with the result of the last chain verification. Filter with project, actor, category and security=1; page with limit (up to 500) and before, passing the next value back. format=ndjson streams the whole log, oldest first. Needs the team-audit permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)
  • actor (query, string, optional)
  • before (query, string, optional)
  • category (query, string, optional)
  • format (query, string, optional)
  • limit (query, integer, optional), at most 500, default 100
  • project (query, string, optional)
  • security (query, string, optional)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Create an account invitationPOST /api/v1/accounts/{account}/invitations

Invites a person by email into the team, or as a guest on one project (project_id), and emails them a link that is valid for 14 days. Needs the team-members permission. project_id and projects cannot be combined, owners and admins take no projects, and an address that is already a member or blocked by the team's access list is refused.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)

Body (application/json)

  • email string (email), required, 3 to 320 characters, matches ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
  • role "owner" | "admin" | "developer" | "editor" | "reviewer" | "viewer" | "tester", required
  • project_id string (uuid), matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$: Invite them as a guest on this one project, rather than into the team.
  • projects array of object, at most 500 items: The projects a team member will work on, each with an optional role. Not with project_id.

    A list of:

    • id string (uuid), required, matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
    • role "owner" | "admin" | "developer" | "editor" | "reviewer" | "viewer" | "tester"

201 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 409 Conflict. (code is conflict.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Delete an account invitationDELETE /api/v1/accounts/{account}/invitations/{id}

Revokes a pending invitation, so its link no longer admits anyone. Needs the team-members permission. The revocation is recorded in the team's audit log.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)
  • id (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

List account membersGET /api/v1/accounts/{account}/members

Lists the team's members with their role and join date. Owners and admins also get each member's email and the pending invitations; everyone else sees names and masked addresses. Unpaged.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)

200 Success.

What comes back
  • data array of object, required

    A list of:

    • user_id string, required
    • email string | null, required: In full for an owner or admin. Others see a masked address for a member with no name, and null otherwise.
    • name string | null, required
    • role string, required
    • joined_at string, required: ISO 8601 timestamp.
  • invitations array of object, required: Pending invitations; empty unless the caller is an owner or admin.

    A list of:

    • id string, required
    • email string, required
    • role string, required
    • project_id string | null, required
    • projects array of object, required: The projects they will work on, each with the role they will have there.

      A list of:

      • id string, required
      • role string, required
    • expires_at string, required: ISO 8601 timestamp.
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • default Any other failure, as RFC 9457 problem details.

Update an account memberPATCH /api/v1/accounts/{account}/members/{userId}

Changes a member's team role and reconnects their open editor sessions under the new role. Needs the team-members permission. Only an owner may grant ownership or change another owner, and the last owner cannot be demoted.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)
  • userId (path, string)

Body (application/json)

  • role "owner" | "admin" | "developer" | "editor" | "reviewer" | "viewer" | "tester", required

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 409 Conflict. (code is conflict.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Delete an account memberDELETE /api/v1/accounts/{account}/members/{userId}

Removes a member from the team and closes their open editor connections. Needs the team-members permission. Only an owner may remove another owner, and the team's last owner cannot be removed.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)
  • userId (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 409 Conflict. (code is conflict.)
  • default Any other failure, as RFC 9457 problem details.

Replace a member assignmentPUT /api/v1/accounts/{account}/members/{userId}/assignments

Replaces the full list of projects a member works on, each with an optional role that defaults to their team role; projects left out are taken away. Needs the team-members permission. Owners and admins are refused, since they already reach every project; ids of projects not in the team are skipped.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)
  • userId (path, string)

Body (application/json)

  • projects array of object, at most 500 items, default []: Every project the member works on, replacing the list they had.

    A list of:

    • id string, required: A project of this team. An id that is not (a project deleted since) is skipped.
    • role "owner" | "admin" | "developer" | "editor" | "reviewer" | "viewer" | "tester": Their role on that project; defaults to their team role.

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

List account projectsGET /api/v1/accounts/{account}/projects

Lists the team's projects the caller can see: all of them for owners and admins, otherwise the assigned ones. Projects scheduled for deletion are included with deleted_at and purge_after. Unpaged data list.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)

200 Success.

What comes back
  • data array of object, required

    A list of:

    • id string, required
    • slug string, required
    • name string, required
    • status string, required
    • state string, required
    • live_branch string, required
    • publish_policy string, required
    • has_published boolean, required: Has this project ever served anything? status: active only means the repository is ready, minutes before the first build lands.
    • created_at string, required: ISO 8601 timestamp.
    • my_session object: The caller’s own newest editing session here; absent when they have none.
      • id string, required
      • title string, required
      • updated_at string, required: ISO 8601 timestamp.
    • deleted_at string: Present only while a deletion is pending.
    • purge_after string: Present only while a deletion is pending.
    • clone_url string: Where to push; sent only while the project waits for its first push.
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • default Any other failure, as RFC 9457 problem details.

Create an account projectPOST /api/v1/accounts/{account}/projects

Creates a project from a template (template, starter by default: an id from GET /api/v1/templates, or team:<id> for one of the team's own from GET /api/v1/accounts/{account}/templates) and queues its setup; the answer is 201 with the project's id, slug and status, and setup continues in the background. Needs the project-create permission. A slug already used in the team, or a reserved one, is refused, and so is a team already at its project limit.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)
  • Idempotency-Key (header, string, optional): Optional. A key the caller chooses, at most 160 characters, kept per team. A repeat of the same request (method, path and body) under the same key is answered with the first result and the header Idempotent-Replay: true, and the work is not done twice. The same key with a different request answers 409; so does a repeat sent while the first is still running, with Retry-After: 5.

Body (application/json)

  • name string, required, 1 to 80 characters
  • slug string, at most 60 characters
  • template string, 1 to 60 characters, default "starter"

201 Success. Headers: Idempotent-Replay.

What comes back
  • id string, required
  • slug string, required
  • status string, required
  • message string, required
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 409 Conflict. (code is conflict.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

List account templatesGET /api/v1/accounts/{account}/templates

Lists the templates the team saved from its own projects, newest first, with each one's template (pass it as template when creating a project in this team), status (only ready can start a project; failed carries its error), the project it came from, its size and its pages, plus the team's limits. Needs the project-create permission (owner and admin). Another team's templates are never listed and cannot be used.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)

200 Success.

What comes back
  • data array of object, required

    A list of:

    • id string, required
    • template string, required: What to pass as template when creating a project: team:<id>.
    • name string, required
    • description string, required
    • status "saving" | "ready" | "failed", required: Only a ready one can start a project.
    • error string: Why a failed one was not saved.
    • source_project string, required: The name of the project it was saved from, when it was saved.
    • source_project_id string | null, required: Null once that project is deleted.
    • source_commit string, required
    • stack_version string | null, required
    • bytes number | null, required
    • files number | null, required
    • pages array of string, required
    • created_by string | null, required
    • created_at string, required: ISO 8601 timestamp.
  • limits object, required
    • count number, required: How many templates a team may keep (MAX_TEMPLATES_PER_ACCOUNT).
    • bytes number, required: How large one may be as stored (MAX_TEMPLATE_BYTES).
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Get account usageGET /api/v1/accounts/{account}/usage

Returns the team's usage against the platform caps: projects, builds in the last 24 hours and queued jobs, each with used and limit, plus the upload and per-project media size limits. Any member may read it.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • account (path, string)

200 Success.

What comes back
  • projects object, required
    • used number, required
    • limit number, required
  • builds_24h object, required
    • used number, required
    • limit number, required
  • queued_jobs object, required
    • used number, required
    • limit number, required
  • upload_bytes object, required
    • limit number, required
  • media_bytes_per_project object, required
    • limit number, required
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • default Any other failure, as RFC 9457 problem details.

List teamsGET /api/v1/teams

Lists the teams the caller belongs to, with their role and the counts of members, live projects and projects being deleted, unpaged. scope=all and scope=others are the deployment operator's view, paged with cursor and next and searchable with search.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • cursor (query, string, optional)
  • limit (query, integer, optional), at most 200, default 50
  • scope (query, string, optional)
  • search (query, string, optional)

200 Success.

What comes back
  • scope "mine" | "all" | "others", required
  • total number: With scope=all or others only.
  • next string | null: With scope=all or others only: the cursor for the next page.
  • data array of object, required

    A list of:

    • id string, required
    • slug string, required
    • name string, required
    • type string, required
    • plan string, required
    • role string | null, required: The caller’s role; null for a team they are not in.
    • created_at string, required: ISO 8601 timestamp.
    • deleted_at string: Present only while a deletion is pending.
    • members number, required
    • projects number, required
    • projects_deleting number, required
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.