Boards

Boards are curated collections of circuits. Think of them as playlists for your AI workflows — group related circuits together so they're easy to find, share, and revisit. You might build a board for "Finance Research", another for "Customer Support Agents", or one just to track your favorite public circuits from the community.

Every board has an owner, a name, and a visibility setting. Private boards are only visible to you, while public boards can be discovered and starred by anyone on ModelWorks.

Base URL

All examples assume the following base URL:

https://modelworks.ai/api

Authentication

Most board endpoints require an API token sent as a Bearer token:

Authorization: Bearer YOUR_API_TOKEN

Reading a public board (or listing the circuits in one) needs no auth — but including your token can improve what you see.

Create a Board

POST /boards

Create a new board under your account.

curl -X POST https://modelworks.ai/api/boards \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finance Research",
    "description": "Circuits for SEC filings and dilution analysis",
    "is_private": false,
    "is_protected": false
  }'

Returns the created board object, including its uid.

List Your Boards

GET /boards

List every board you own. Supports pagination.

curl "https://modelworks.ai/api/boards?limit=20&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Returns a paginated response with a meta block (total_count, limit, page) and a data array of boards.

Get a Board

You can fetch a board two ways: by its UID, or by the owner's username and the board's name.

GET /boards/{board_uid}

Fetch a single board by its unique identifier. Visibility-gated: public boards return for anyone, private boards return only for the owner. Auth is optional — sending your token helps the server decide what you may see.

curl https://modelworks.ai/api/boards/8a2c1f4e-1234-4abc-9def-1234567890ab \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET /boards/by-username/{username}/{board_name}

Fetch a board using the owner's username and the board's name. Useful when you only have a profile URL to work with.

curl https://modelworks.ai/api/boards/by-username/janedoe/finance-research \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update a Board

PUT /boards/{board_uid}

Update a board's name, description, or visibility. Only the board owner may do this.

curl -X PUT https://modelworks.ai/api/boards/8a2c1f4e-1234-4abc-9def-1234567890ab \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for my finance board",
    "is_private": true
  }'

Delete a Board

DELETE /boards/{board_uid}

Permanently delete a board. Only the board owner may do this. Deleting a board does not delete the circuits inside it — it only removes the collection.

curl -X DELETE https://modelworks.ai/api/boards/8a2c1f4e-1234-4abc-9def-1234567890ab \
  -H "Authorization: Bearer YOUR_API_TOKEN"

List Circuits in a Board

GET /boards/{board_uid}/circuits

List the circuits that have been added to a board. Visibility-gated: for a private board you must be the owner; for a public board anyone can list. Auth is optional.

curl "https://modelworks.ai/api/boards/8a2c1f4e-1234-4abc-9def-1234567890ab/circuits?limit=20&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Add a Circuit to a Board

POST /boards/{board_uid}/circuits

Add a circuit to one of your boards. Only the board owner may add circuits.

curl -X POST https://modelworks.ai/api/boards/8a2c1f4e-1234-4abc-9def-1234567890ab/circuits \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "circuit_uid": "73120d53-bf89-44fa-a035-5b88fe41574a"
  }'

Remove a Circuit from a Board

DELETE /boards/{board_uid}/circuits/{circuit_uid}

Remove a circuit from a board. Only the board owner may remove circuits. Removing a circuit from a board does not delete the circuit itself.

curl -X DELETE https://modelworks.ai/api/boards/8a2c1f4e-1234-4abc-9def-1234567890ab/circuits/73120d53-bf89-44fa-a035-5b88fe41574a \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Star and Unstar Boards

Starring is a way to bookmark boards you find interesting. Stars are public signals — they help surface great boards to others.

All three endpoints are scoped by the owner's username and the board's name, and require an API token.

GET /users/{username}/boards/{board_name}/stars

Check whether you have starred a given board. Returns your star record if you have, or a not-found response if you haven't.

curl https://modelworks.ai/api/users/janedoe/boards/finance-research/stars \
  -H "Authorization: Bearer YOUR_API_TOKEN"

POST /users/{username}/boards/{board_name}/stars

Star a board.

curl -X POST https://modelworks.ai/api/users/janedoe/boards/finance-research/stars \
  -H "Authorization: Bearer YOUR_API_TOKEN"

DELETE /users/{username}/boards/{board_name}/stars

Unstar a board.

curl -X DELETE https://modelworks.ai/api/users/janedoe/boards/finance-research/stars \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Check Board Access

GET /users/{username}/boards/{board_name}/ping

A lightweight read-access probe. Returns a boolean: true if the caller can read the board, false otherwise. Handy for client-side gating before trying to render a board. Auth is optional — including your token determines whether private boards you own report true.

curl https://modelworks.ai/api/users/janedoe/boards/finance-research/ping \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Error Responses