Create a draft awards program

POST/v1/organization/{orgId}/awards/workspace/programs

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

Creates a working draft that is ready to review: the program with you as a manager, its categories (yours, or the starter categories for the organization's audience, at most 50), a four-question nomination form, a scorecard (Impact, Originality and Evidence on a 1–5 scale, plus comments) on the program's one review pass, and the winner types Winner and Finalist. The deadline sets the review pass dates: nominations from now until the deadline (30 days from now when omitted), then three weeks of review. Nothing is public and nothing is sent until nominations are opened. Requires write:awards; the token's user needs the Awards create permission. Refused for a key restricted to particular events. Also at POST /v1/awards/workspace/programs.

Request example

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

const response = await fetch('https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs', {
  method: 'POST',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "<string>",
    "description": "<string>",
    "categories": [
      "<string>"
    ],
    "deadline": "2026-01-15T09:30:00Z",
    "nominationMode": "nominate_others",
    "source": {
      "client": "<string>",
      "version": "<string>",
      "run_id": "<string>",
      "prompt": "<string>"
    }
  }),
});

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

import requests

response = requests.request(
    "POST",
    "https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "name": "<string>",
        "description": "<string>",
        "categories": [
            "<string>"
        ],
        "deadline": "2026-01-15T09:30:00Z",
        "nominationMode": "nominate_others",
        "source": {
            "client": "<string>",
            "version": "<string>",
            "run_id": "<string>",
            "prompt": "<string>"
        }
    },
)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{
  "name": "<string>",
  "description": "<string>",
  "categories": [
    "<string>"
  ],
  "deadline": "2026-01-15T09:30:00Z",
  "nominationMode": "nominate_others",
  "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;

package main

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

func main() {
  req, _ := http.NewRequest("POST", "https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs", strings.NewReader(`{
  "name": "<string>",
  "description": "<string>",
  "categories": [
    "<string>"
  ],
  "deadline": "2026-01-15T09:30:00Z",
  "nominationMode": "nominate_others",
  "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))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"categories\": [\n    \"<string>\"\n  ],\n  \"deadline\": \"2026-01-15T09:30:00Z\",\n  \"nominationMode\": \"nominate_others\",\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

Response headers

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.

Request body

application/jsonrequired

namestringrequired
Min length
1
Max length
200
descriptionstring
Max length
2000
categoriesstring[]
Category names, in order. Omit (or send []) for the audience's starter categories.
Max items
50
deadlinestring<date-time>
When nominations close, as a full date and time with a time zone (for example 2026-12-01T17:00:00Z). 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

Example

{
  "name": "<string>",
  "description": "<string>",
  "categories": [
    "<string>"
  ],
  "deadline": "2026-01-15T09:30:00Z",
  "nominationMode": "nominate_others",
  "source": {
    "client": "<string>",
    "version": "<string>",
    "run_id": "<string>",
    "prompt": "<string>"
  }
}

Responses

201`application/json`

Created

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>

400`application/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.

403`application/json`

One of the codes in AwardsWorkspaceWriteForbidden, or FORBIDDEN with a message saying the plan does not allow another awards program (Enterprise organizations have a program limit; self-serve Awards plans do not).

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

404`application/json`

NOT_FOUND: orgId is not the token's organization.

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

423`application/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.

429`application/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"
    }
  }
}

{
  "error": "VALIDATION_ERROR",
  "message": "Error on body parameter: data should NOT have additional properties: \"winners\""
}

{
  "error": "FORBIDDEN",
  "message": "You have reached the maximum number of award programs (3) for your account. Contact your Sessionboard account manager to increase your limit."
}

{
  "error": "NOT_FOUND",
  "message": "Organization not found"
}

{
  "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"
}

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

Create a draft awards program

Request example

Try it

Authorizations

Path parameters

Request body

Responses

201application/json

400application/json

401

403application/json

404application/json

423application/json

429application/json

Response examples

201`application/json`

400`application/json`

403`application/json`

404`application/json`

423`application/json`

429`application/json`