Modify board state¶

PUT /api/v5/org/{owner}/kanban/{kanban_id}/state

This endpoint modifies the state of a board under the specified organization. It can set the board to open or closed. It locates the target board by the organization path and board ID, and specifies the desired state value in the request body.

Access token support¶

• AtomGit user access token (AtomGit user access tokens)

Anonymous access¶

This endpoint allows anonymous access.

Request parameters¶

Request Body:

The request body is a JSON object that specifies the board state to set.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "state": {
      "description": "Board state, closed: closed; open: open",
      "type": "string",
      "enum": ["closed", "open"]
    }
  },
  "required": ["state"]
}

Response parameters¶

On success, this endpoint returns 200 with no response body.

Error responses¶

A success response alone is not enough: callers need to know what failures look like in order to write error handling.

400 Invalid parameters

Returned when state is neither closed nor open:

{
  "errorCode": 400,
  "errorCodeName": "BAD_REQUEST",
  "errorMessage": "The value of the state must be either 'closed' or 'open'",
  "traceId": ""
}

404 Not found

Returned when the organization does not exist:

{
  "errorCode": 404,
  "errorCodeName": "NOT_FOUND",
  "errorMessage": "Not Found",
  "traceId": ""
}

HTTP response status codes¶

Request example¶

Parameter description¶

The examples must be consistent with the rest of this document; copy them as-is and the call succeeds:

Replace <owner> with the organization path (the address path of an enterprise, organization, or individual); replace <kanban_id> with the board ID; if you carry a token, replace <token> with your AtomGit user access token.

This endpoint allows anonymous access; you may omit the token. When carrying one, append ?access_token=<token> to the URL.

cURL¶

curl -X PUT 'https://api.atomgit.com/api/v5/org/<owner>/kanban/<kanban_id>/state' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"state": "open"}'

When carrying an access token:

curl -X PUT 'https://api.atomgit.com/api/v5/org/<owner>/kanban/<kanban_id>/state?access_token=<token>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"state": "open"}'

JavaScript¶

// Native fetch (Node.js 18+ / browser)
const response = await fetch("https://api.atomgit.com/api/v5/org/<owner>/kanban/<kanban_id>/state", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({ state: "open" }),
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

Python¶

import requests

resp = requests.put(
    "https://api.atomgit.com/api/v5/org/<owner>/kanban/<kanban_id>/state",
    json={"state": "open"},
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()

Response example¶

Status code: 200

This endpoint returns no response body after a successful modification.

Error codes¶