Replace a program's categories

PUT/v1/organization/{orgId}/awards/workspace/programs/{programId}/categories

US Region: https://public-api.sessionboard.com · EU Region: https://public-api-eu.sessionboard.com

Sends the program's full category list, in order (1 to 50). A category with an id is kept (renamed and moved as sent); one without an id is added; any existing category left out is removed. Send back the categories_revision you read as baseRevision and a list built from an out-of-date read is refused with 409 instead of undoing someone else's change. Sends nothing. Requires write:awards; the token's user needs the Awards update permission and must manage the program. Refused for a key restricted to particular events. Also at PUT /v1/awards/workspace/programs/{programId}/categories.

Request example

cURL

curl --request PUT \
  --url 'https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/categories' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "categories": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    }
  ],
  "baseRevision": "<string>",
  "source": {
    "client": "<string>",
    "version": "<string>",
    "run_id": "<string>",
    "prompt": "<string>"
  }
}'

JavaScript

const response = await fetch('https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/categories', {
  method: 'PUT',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "categories": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>"
      }
    ],
    "baseRevision": "<string>",
    "source": {
      "client": "<string>",
      "version": "<string>",
      "run_id": "<string>",
      "prompt": "<string>"
    }
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.request(
    "PUT",
    "https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/categories",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "categories": [
            {
                "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                "name": "<string>"
            }
        ],
        "baseRevision": "<string>",
        "source": {
            "client": "<string>",
            "version": "<string>",
            "run_id": "<string>",
            "prompt": "<string>"
        }
    },
)

print(response.json())

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/categories",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_POSTFIELDS => '{
  "categories": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    }
  ],
  "baseRevision": "<string>",
  "source": {
    "client": "<string>",
    "version": "<string>",
    "run_id": "<string>",
    "prompt": "<string>"
  }
}',
    CURLOPT_HTTPHEADER => [
        "x-access-token: <api-token>",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

func main() {
  req, _ := http.NewRequest("PUT", "https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/categories", strings.NewReader(`{
  "categories": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    }
  ],
  "baseRevision": "<string>",
  "source": {
    "client": "<string>",
    "version": "<string>",
    "run_id": "<string>",
    "prompt": "<string>"
  }
}`))
  req.Header.Add("x-access-token", "<api-token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(string(body))
}

Java

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/categories"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("PUT", HttpRequest.BodyPublishers.ofString("{\n  \"categories\": [\n    {\n      \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"baseRevision\": \"<string>\",\n  \"source\": {\n    \"client\": \"<string>\",\n    \"version\": \"<string>\",\n    \"run_id\": \"<string>\",\n    \"prompt\": \"<string>\"\n  }\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Try it

RegionUS Region — https://public-api.sessionboard.comEU Region — https://public-api-eu.sessionboard.com

Authorization

Send asAPI token (x-access-token)OAuth access token (Bearer)

Token

Your token stays in this page. It is sent only to the region above and is never saved; it is gone when you leave or reload the page.

Path parameters

orgId*

programId*

Body application/json

{ "categories": [ { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "name": "<string>" } ], "baseRevision": "<string>", "source": { "client": "<string>", "version": "<string>", "run_id": "<string>", "prompt": "<string>" } }

PUT

Send request

Authorizations

• x-access-tokenstringheader

  Organization API token. Generate from Organization Settings → API Tokens.

• AuthorizationBearer <token>headeror

  OAuth 2.1 access token. Obtained via the OAuth PKCE flow at /oauth/token.

Send one of these. See Authentication.

Path parameters

• orgIdstringpathrequired

  Your organization ID. Any other organization returns 404.

• programIdstring<uuid>pathrequired

  The Awards program ID.

Request body

application/jsonrequired

• categoriesobject[]required

  Min items

  1

  Max items

  50

  Show child attributes

  • idstring<uuid>

    An existing category of this program. Omit to add a new one.

  • namestringrequired

    Min length

    1

    Max length

    120

• baseRevisionstring

  The categories_revision the list was built from. Optional, but without it nothing guards against a stale read.

  Max length

  64

• sourceAwardsWorkspaceSource

  Optional on every write: which assistant is calling and what the person asked it. Recorded with the change in the organization's activity and on any approval request; never stored on the program.

  Show child attributes

  • clientstring

    The assistant's client name (for example Claude or ChatGPT).

  • versionstring
  • run_idstring

    Your own id for the conversation.

  • promptstring

    What the person asked the assistant.

    Max length

    2000

Example

{
  "categories": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    }
  ],
  "baseRevision": "<string>",
  "source": {
    "client": "<string>",
    "version": "<string>",
    "run_id": "<string>",
    "prompt": "<string>"
  }
}

Responses

200application/json

OK

• successboolean
• payloadobject
  Show child attributes

  • categoriesAwardsWorkspaceCategory[]
    Show child attributes

    • idstring<uuid>
    • namestring
  • categories_revisionstring

    Send this as baseRevision with the next replacement.

400application/json

VALIDATION_ERROR: the body does not match the schema, or an id is not a category of this program (A category does not belong to this program.).

Error body for the Awards workspace operations.

• errorstringrequired

  Allowed values

  "VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"

• messagestringrequired
• codestring

  A more specific reason, when there is one (trial_ended, plan_ended).

401

Missing, invalid or expired token.

403application/json

• SCOPE_REQUIRED: the token lacks write:awards. Legacy tokens with no scopes cannot write.
• ORG_WIDE_TOKEN_REQUIRED: the key is restricted to particular events. The Awards workspace covers every awards program in the organization, so use a key without an event restriction.
• FORBIDDEN with code: trial_ended or code: plan_ended: the organization's self-serve Awards plan is read-only (the trial ended, or the plan was canceled or is unpaid). Everything can still be read; choose a plan to make changes.
• FORBIDDEN with no code: the token's user is not an active member of the organization, lacks the Awards permission the operation needs, does not manage the program, or (for the setup answers) is not an organization admin.

These operations do not return enterprise_only; the Enterprise-only items are listed by GET /v1/organization/{orgId}/awards/workspace/enterprise.

Error body for the Awards workspace operations.

• errorstringrequired

  Allowed values

  "VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"

• messagestringrequired
• codestring

  A more specific reason, when there is one (trial_ended, plan_ended).

404application/json

NOT_FOUND: orgId is not the token's organization, or the program is not in it.

Error body for the Awards workspace operations.

• errorstringrequired

  Allowed values

  "VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"

• messagestringrequired
• codestring

  A more specific reason, when there is one (trial_ended, plan_ended).

409application/json

CONFLICT: the categories changed since baseRevision was read. Read the program again and resend the full list.

Error body for the Awards workspace operations.

• errorstringrequired

  Allowed values

  "VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"

• messagestringrequired
• codestring

  A more specific reason, when there is one (trial_ended, plan_ended).

423application/json

A person has paused connected assistants for the organization, so writes from the API wait until they resume it in Sessionboard. code is AGENT_WRITES_PAUSED.

Error body for 423.

• statusinteger
• successboolean
• messagestring
• namestring
• codestring
• paused_atstring<date-time>

  When assistants were paused.

429application/json

• The token's request limit (100 requests per 15 minutes by default, per bucket). Wait Retry-After seconds. The body is the TooManyRequestsError shape — see Rate Limiting.
• Writes only: QUOTA_EXCEEDED, the token's daily write quota (10,000 writes a day). It resets at midnight UTC.

• responseTooManyRequestsError | AwardsWorkspaceError
  name: TooManyRequestsError (TooManyRequestsError)

  Body of a 429 from the API's own request limits (per token, and per organization and user). Wait Retry-After seconds.

  • statusinteger

    Example

    429

  • successboolean

    Example

    false

  • messagestringrequired

    Example

    "Error while trying to reach the endpoint: Too many requests"

  • namestringrequired

    Allowed values

    "TooManyRequestsError"

  Option 2 (AwardsWorkspaceError)

  Error body for the Awards workspace operations.

  • errorstringrequired

    Allowed values

    "VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"

  • messagestringrequired
  • codestring

    A more specific reason, when there is one (trial_ended, plan_ended).

• Retry-Afterintegerheader

  Seconds to wait before retrying.

Response examples

200

{
  "success": true,
  "payload": {
    "categories": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>"
      }
    ],
    "categories_revision": "<string>"
  }
}

400

{
  "error": "VALIDATION_ERROR",
  "message": "A category does not belong to this program."
}

403 · Token lacks the write scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This operation requires the 'write:awards' scope."
}

403 · Key restricted to particular events

{
  "error": "ORG_WIDE_TOKEN_REQUIRED",
  "message": "The Awards workspace covers every awards program in the organization, so this API key (restricted to particular events) cannot use it. Use a key without an event restriction."
}

403 · The self-serve trial has ended

{
  "error": "FORBIDDEN",
  "message": "Your Awards trial has ended. Choose a plan to keep going; everything you made is still here.",
  "code": "trial_ended"
}

403 · The self-serve plan is read-only

{
  "error": "FORBIDDEN",
  "message": "Your Awards plan has ended, so the workspace is read-only. Choose a plan to pick up where you left off.",
  "code": "plan_ended"
}

403 · The token's user does not manage the program

{
  "error": "FORBIDDEN",
  "message": "User is not a manager of this program"
}

404

{
  "error": "NOT_FOUND",
  "message": "Awards Program could not be found"
}

409

{
  "error": "CONFLICT",
  "message": "The categories changed since you read them. Read the program again and resend the full list."
}

423

{
  "status": 423,
  "success": false,
  "message": "A person has paused connected assistants in Sessionboard. Ask them to resume it from their workspace before trying again.",
  "name": "AgentWritesPausedError",
  "code": "AGENT_WRITES_PAUSED",
  "paused_at": "2026-11-06T15:04:05.000Z"
}

429

{
  "status": 429,
  "success": false,
  "message": "Error while trying to reach the endpoint: Too many requests",
  "name": "TooManyRequestsError"
}