Skip to content
SessionboardSessionboardSessionboard Help Center

Update an awards program

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

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

Changes the program's name, description, nomination deadline or nomination mode. Only the fields you send change. A new deadline moves the review pass with it: review starts at the deadline and runs three weeks. The nomination mode cannot change once the program has a nomination (422). 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}.

Request example

Terminal window
curl --request PUT \
  --url 'https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "description": "<string>",
  "deadline": "2026-01-15T09:30:00Z",
  "nominationMode": "nominate_others",
  "source": {
    "client": "<string>",
    "version": "<string>",
    "run_id": "<string>",
    "prompt": "<string>"
  }
}'

Try it

Authorization

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
Body application/json
PUT

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/json

  • namestring
    Min length
    1
    Max length
    200
  • descriptionstring

    An empty string clears it.

    Max length
    2000
  • deadlinestring<date-time>

    When nominations close, as a full date and time with a time zone. A date alone is refused.

  • nominationModestring

    nominate_others: people nominate someone else. self_only: people submit for themselves. Defaults to the audience's mode.

    Allowed values
    "nominate_others", "self_only"
  • 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
{
  "name": "<string>",
  "description": "<string>",
  "deadline": "2026-01-15T09:30:00Z",
  "nominationMode": "nominate_others",
  "source": {
    "client": "<string>",
    "version": "<string>",
    "run_id": "<string>",
    "prompt": "<string>"
  }
}

Responses

200application/json

OK

  • successboolean
  • payloadobject
    Show child attributes
    • programAwardsWorkspaceProgram
      Show child attributes
      • idstring<uuid>
      • namestring
      • nomenclaturestring
        Allowed values
        "awards", "grants", "scholarships"
      • descriptionstring | null
      • nomination_modestring

        nominate_others: people nominate someone else. self_only: people submit for themselves. Defaults to the audience's mode.

        Allowed values
        "nominate_others", "self_only"
      • statusstring

        Worked out from the dates: open while it is on the Awards Site and its nomination window is running, reviewing after nominations close, closed when it has nominations and every date has passed.

        Allowed values
        "draft", "open", "reviewing", "closed", "archived"
      • decidedboolean

        At least one winner has been picked.

      • roundAwardsWorkspaceRound | any | null
        Show child attributes
        • idstring<uuid>
        • namestring
        • submission_start_datestring<date-time> | null
        • submission_end_datestring<date-time> | null

          The nomination deadline.

        • review_start_datestring<date-time> | null
        • review_end_datestring<date-time> | null
      • roundsinteger

        How many Rounds the program has (one on self-serve).

      • categoriesAwardsWorkspaceCategory[]
        Show child attributes
        • idstring<uuid>
        • namestring
      • categories_revisionstring

        Send this as baseRevision when replacing the categories.

      • public_urlstring | null

        The program's sign-in page on the Awards Site, once it has been opened. Empty when the Site has no address yet.

      • countsAwardsWorkspaceProgramCounts
        Show child attributes
        • submittedinteger

          Submitted nominations.

        • draftsinteger

          Nominations started and not submitted.

        • reviewersinteger
        • scorecardsinteger

          Finished scorecards.

        • reviewedinteger

          Submitted nominations with at least one finished scorecard.

        • winnersinteger
      • created_atstring<date-time>

400application/json

VALIDATION_ERROR: the body or a path id does not match the schema. Unknown body fields are refused and named in the message; source is always accepted.

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).

422application/json

The program has nominations, so its nomination mode cannot change. Duplicate the program to run it with the other mode.

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

{
  "success": true,
  "payload": {
    "program": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "nomenclature": "awards",
      "description": "<string>",
      "nomination_mode": "nominate_others",
      "status": "draft",
      "decided": true,
      "round": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "submission_start_date": "2026-01-15T09:30:00Z",
        "submission_end_date": "2026-01-15T09:30:00Z",
        "review_start_date": "2026-01-15T09:30:00Z",
        "review_end_date": "2026-01-15T09:30:00Z"
      },
      "rounds": 123,
      "categories": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>"
        }
      ],
      "categories_revision": "<string>",
      "public_url": "<string>",
      "counts": {
        "submitted": 123,
        "drafts": 123,
        "reviewers": 123,
        "scorecards": 123,
        "reviewed": 123,
        "winners": 123
      },
      "created_at": "2026-01-15T09:30:00Z"
    }
  }
}