---
title: "Projects API | Jetstack AI Docs"
description: "Drive a Jetstack AI project over REST: bind a portal, build the brief, chat with Jetty, approve builds and deploys, and read runs and receipts."
url: "https://jetstack.ai/docs/developers/projects-api/"
---

# Projects API

The Projects API gives your scripts, CLI tools and agents the same project that you see in the app. Everything a person can do in a project has an endpoint: bind the client’s portal, upload documents and review the brief, derive the blueprint, chat with Jetty, approve plans and deploys, and read the runs and receipts that show what HubSpot accepted.

This page explains how the API works and walks through the most common flow. The [API reference](https://jetstack.ai/api) lists every Projects endpoint with its parameters, scope and refusal codes. If you haven’t used Projects in the app yet, read the [Projects Overview](https://jetstack.ai/docs/projects) first: the API follows the same model of chats, cards and receipts.

Projects is currently in **limited release** and isn’t turned on by default. Call `GET /v1/projects/enabled` to check your organization. Until it is enabled, every other Projects endpoint returns `403` with `PROJECTS_NOT_ENABLED`. See [Getting Access](https://jetstack.ai/docs/projects/getting-access).

## Before You Start

- **Base URL:** `https://api.jetstack.ai`. All Projects endpoints live under `/v1/projects`.
- **Authentication:** send your API key as `Authorization: Bearer jsai_…`. Create keys in the app under **Settings → Access Tokens** and choose their scopes there.
- **Dedicated instances only:** if your organization runs on a dedicated Jetstack instance, also send `X-Instance-Id` with the value shown in **Settings → Access Tokens → Connection Details**. Everyone else leaves it out.

See [Authentication](https://jetstack.ai/docs/developers/authentication) for key management and rate limits. The examples below assume:

Terminal window

```
export  JETSTACK_API_KEY = "jsai_your_api_key"
export  PROJECT_ID = "prj_8Hq2xL0vT3"
```

## How Authorization Works

Every request passes two checks, and both must pass:

1. **The key’s scope.** Each endpoint needs one `projects:*` scope. The scope says what the key is allowed to attempt.
2. **The key creator’s role on the project.** A key acts as the person who created it. Their role on this project (`viewer`, `editor` or `owner`) decides which actions they can take, exactly as it does in the app.

So a key can never do more than the person who created it. A full-access key created by someone who isn’t a member of a project can only read it: an organization member who isn’t on the project counts as a `viewer`. If the key’s creator leaves your organization, the key is refused with `403`.

### Scopes

| Scope               | What it unlocks                                                                                                                                                    | In presets                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
| `projects:read`     | Every `GET` endpoint                                                                                                                                               | Read-only, operator, full-access |
| `projects:write`    | Starting, renaming and archiving chats; answering or declining cards; resolving brief decisions; rescanning the portal; verifying assets; marking setup items done | Full-access                      |
| `projects:chat`     | Sending chat messages and uploading documents                                                                                                                      | Full-access                      |
| `projects:generate` | Anything that spends credits: document analysis, AI suggestions, deriving the blueprint, approving a plan, repairing or restoring an asset, resuming a paused run  | Full-access                      |
| `projects:deploy`   | Anything that changes the client’s portal: approving deploy, fix and retire cards, and retiring an asset                                                           | **None**                         |
| `projects:admin`    | Creating, renaming and archiving projects; managing members; binding the portal                                                                                    | Full-access                      |
| `projects:billing`  | Buying credits                                                                                                                                                     | **None**                         |

`projects:deploy` and `projects:billing` are left out of every preset, including full-access, because they deploy to a client’s production portal and spend money. Tick them deliberately when you create a key that needs them.

### Roles

| Role     | Can do                                                                                                      |
| -------- | ----------------------------------------------------------------------------------------------------------- |
| `viewer` | Read the project                                                                                            |
| `editor` | Everything a viewer can, plus chat, build, repair, detach and remove assets                                 |
| `owner`  | Everything an editor can, plus deploy to the portal, connect the portal, change settings and manage members |

Deploying to the portal (approving a deploy card, or a fix card that redeploys) needs both `projects:deploy` on the key and an `owner` role for the key’s creator. `GET /v1/projects/roles` returns the full role-to-capability table.

### Check Before You Call

You don’t have to call an endpoint to find out whether a key can use it. `GET /v1/projects/{projectId}/access` returns both halves of the check and the result for each capability:

Terminal window

```
curl   https://api.jetstack.ai/v1/projects/ $PROJECT_ID /access   \
   -H   "Authorization: Bearer  $JETSTACK_API_KEY "
```

```
{
   "data" : {
     "projectId" :  "prj_8Hq2xL0vT3" ,
     "portalId" :  "244840437" ,
     "role" :  "editor" ,
     "key" : {
       "keyPrefix" :  "jsai_4kTz9m...b81c" ,
       "createdBy" :  "user_2abcDEF" ,
       "projectScopes" : [ "projects:read" ,  "projects:write" ,  "projects:chat" ,  "projects:generate" ]
     },
     "capabilities" : [
       {  "capability" :  "project.read" ,  "role" :  true ,  "scope" :  "projects:read" ,  "scopeGranted" :  true ,  "effective" :  true  },
       {  "capability" :  "asset.materialize" ,  "role" :  true ,  "scope" :  "projects:generate" ,  "scopeGranted" :  true ,  "effective" :  true  },
       {  "capability" :  "deploy.production" ,  "role" :  false ,  "scope" :  "projects:deploy" ,  "scopeGranted" :  false ,  "effective" :  false ,  "blockedBy" :  "both"  }
     ],
     "actions" : [],
     "computedAt" :  "2026-10-14T10:02:13.480Z"
   }
}
```

The response above is shortened: `capabilities` lists every capability, and `actions` lists the project-level actions with `available` and, when unavailable, `unavailableReason`. `effective` is the only field that decides a request. When it is `false`, `blockedBy` says whether the `role`, the `scope` or `both` are missing.

## From Brief to Receipt

A project moves through the same stages over the API as in the app:

| Stage                 | What happens                                                                                                                | Main endpoints                                                           |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Portal**            | The project is created on one HubSpot portal, which Jetstack scans                                                          | `POST /v1/projects`, `GET .../portal`                                    |
| **Brief**             | Uploaded documents and conversations become the project’s Knowledge: the brief, its claims and a queue of decisions for you | `POST .../documents`, `GET .../knowledge`, `GET .../knowledge/decisions` |
| **Blueprint**         | The plan of record, derived from the published Knowledge                                                                    | `GET .../blueprint`, `POST .../blueprint/derive`                         |
| **Generate**          | In a chat, Jetty proposes a plan card. Approving it builds the assets                                                       | `POST .../chats/{chatId}/messages`, `POST .../chats/{chatId}/act`        |
| **Deploy**            | Jetty posts a deploy card. Approving it deploys exactly what’s on the card                                                  | `POST .../chats/{chatId}/act`                                            |
| **Runs and receipts** | Every build, deploy and removal is a run, with a receipt for each asset                                                     | `GET .../runs`, `GET .../deploy-log`                                     |

There is no sandbox or production switch in any request. One project is one portal, and every call works on the portal the project is bound to. To work on a sandbox and a production portal, create a project for each.

### Worked Example

1. **Create the project.** This needs `projects:admin`. `portalId` is a HubSpot portal already connected to your organization. Set `runAudit` to `true` to start the onboarding scan straight away.

   Terminal window

   ```
   curl   -X   POST   https://api.jetstack.ai/v1/projects   \
      -H   "Authorization: Bearer  $JETSTACK_API_KEY "   \
      -H   "Content-Type: application/json"   \
      -H   "Idempotency-Key: $( uuidgen )"   \
      -d   '{ "name": "Acme renewals rebuild", "portalId": "244840437", "runAudit": true }'
   ```

   The response is `201` with the project. Keep its `id`.

2. **Start a chat.** Each chat is one task. This needs `projects:write`.

   Terminal window

   ```
   curl   -X   POST   https://api.jetstack.ai/v1/projects/ $PROJECT_ID /chats   \
      -H   "Authorization: Bearer  $JETSTACK_API_KEY "   \
      -H   "Content-Type: application/json"   \
      -H   "Idempotency-Key: $( uuidgen )"   \
      -d   '{ "title": "Set up the renewals pipeline" }'
   ```

   The response is `201` with `data.chat.chatId`.

3. **Upload a build spec.** Send one file per request in a multipart `file` field. Uploading needs `projects:chat`. Pass `chatId` so the analysis is posted into that chat; analysis spends credits, so it also needs `projects:generate`.

   Terminal window

   ```
   curl   -X   POST   "https://api.jetstack.ai/v1/projects/ $PROJECT_ID /documents?chatId= $CHAT_ID "   \
      -H   "Authorization: Bearer  $JETSTACK_API_KEY "   \
      -F   "file=@renewals-spec.pdf"
   ```

   The response includes `analysis: { started, operationId }`. If analysis couldn’t start (no `chatId`, no `projects:generate`, not enough credits), the file is still stored and `analysis.started` is `false` with the reason. Poll `GET .../operations/{operationId}` until it reaches `succeeded`, `partial` or `failed`.

4. **Review the brief.** `GET .../knowledge` returns the published brief. `GET .../knowledge/decisions` returns everything waiting for a person, such as conflicting facts and open questions, with the resolutions each one allows. Resolve one with the version you read it at:

   Terminal window

   ```
   curl   -X   POST   https://api.jetstack.ai/v1/projects/ $PROJECT_ID /knowledge/decisions/ $DECISION_ID /resolve   \
      -H   "Authorization: Bearer  $JETSTACK_API_KEY "   \
      -H   "Content-Type: application/json"   \
      -H   "Idempotency-Key: $( uuidgen )"   \
      -d   '{ "resolution": "confirm", "expectedVersion": 4 }'
   ```

   If someone resolved it first, you get `409` with `KNOWLEDGE_VERSION_CONFLICT` and nothing is overwritten.

5. **Check the blueprint.** `GET .../blueprint` returns the plan of record, its `lifecycle` state (`absent`, `deriving`, `failed`, `current` or `update_available`) and `canDerive`. When `canDerive` is `false`, `cannotDeriveBecause` says why, so you don’t need to try. To derive a new version from the current Knowledge, call `POST .../blueprint/derive`. It spends credits and needs `projects:generate`.

6. **Ask Jetty for a plan.** Send a chat turn. Without `Accept: text/event-stream`, the call waits until Jetty has finished and returns the new messages, including any cards.

   Terminal window

   ```
   curl   -X   POST   https://api.jetstack.ai/v1/projects/ $PROJECT_ID /chats/ $CHAT_ID /messages   \
      -H   "Authorization: Bearer  $JETSTACK_API_KEY "   \
      -H   "Content-Type: application/json"   \
      -H   "Idempotency-Key: $( uuidgen )"   \
      -d   '{ "text": "Build the renewals pipeline and the workflows from the spec." }'
   ```

   Look for a message whose `card.kind` is `plan`, and note its `messageId` and `card.cardId`. If Jetty sends a `questions` card first, answer it (step 7, with `"action": "answer"` and `answers`) and post the returned `followUp` as your next message.

7. **Approve the plan to build.** Approving a plan needs `projects:generate`.

   Terminal window

   ```
   curl   -X   POST   https://api.jetstack.ai/v1/projects/ $PROJECT_ID /chats/ $CHAT_ID /act   \
      -H   "Authorization: Bearer  $JETSTACK_API_KEY "   \
      -H   "Content-Type: application/json"   \
      -H   "Idempotency-Key: $( uuidgen )"   \
      -d   '{ "messageId": "' $MESSAGE_ID '", "cardId": "' $CARD_ID '", "action": "approve" }'
   ```

   The response has `ok`, the card’s new `status` and the `runIds` it started. If the action is refused, `ok` is `false` and `refusal` says why: for example, `card-not-pending` or `card-changed` when the card is no longer the one you read.

8. **Approve the deploy.** When the build is done, read the chat’s messages and approve the `deploy` card the same way. This needs `projects:deploy`, and the key’s creator must be a project `owner`. Approving deploys exactly the snapshot on the card; to leave some assets out, add `excludeAssetIds`.

9. **Read the runs and receipts.** `GET .../runs/{runId}` shows a run in full: counters, progress, every asset that was refused, blocked or failed with HubSpot’s own error, and a credit pause if it stopped for one. `GET .../deploy-log` is the receipt trail, newest first, with each attempt for each asset.

   Terminal window

   ```
   curl   https://api.jetstack.ai/v1/projects/ $PROJECT_ID /runs/ $RUN_ID  \
      -H   "Authorization: Bearer  $JETSTACK_API_KEY "
   ```

Runs have a `kind` (`generation`, `deploy` or `retire`) and a `status`: `queued`, `running`, `waiting_on_extension`, `paused`, `succeeded`, `partial` or `failed`. Filter `GET .../runs` by either, or by `chatId`.

Some asset types deploy through the Jetstack Chrome extension, and parts of a portal scan need it too. An API call can’t do that work itself. It queues the work, which waits in the extension’s **Projects → Inbox** until someone opens the client’s portal in Chrome. A run in `waiting_on_extension`, or an `extensionTaskId` in a card response, means the work isn’t finished when the call returns.

## Credits

Document analysis, AI suggestions, deriving the blueprint, building, and repairing or restoring assets all spend your organization’s [Projects credits](https://jetstack.ai/docs/projects/chats#credits).

- `GET /v1/projects/credits` returns the balance, and `GET /v1/projects/credits/history` the ledger, newest first.
- A request that can’t start for lack of credits returns `402` with `INSUFFICIENT_PROJECT_CREDITS`.
- A build that runs out part-way **pauses** instead of failing (`status: paused`). Add credits, then call `POST .../runs/{runId}/resume` (needs `projects:generate`) to continue where it stopped.
- `POST /v1/projects/credits/purchases` (needs `projects:billing` and an organization admin) returns a checkout URL. A person completes the purchase in a browser; poll `GET /v1/projects/credits/purchases/{sessionId}` for the result.

## Retries and Idempotency

Endpoints that start work or create something accept an `Idempotency-Key` header. The reference marks each one. Use a new UUID per action, up to 256 characters:

- A retry with the same key within 24 hours replays the first successful response with `Idempotent-Replayed: true`, and nothing runs twice.
- The key is also passed to the action itself, so a retry collapses into the original action even if the first response was lost. A retried create returns the same project; a retried card approval returns the first answer.
- The method, path and query string are part of the key’s identity, so the same key on a different request is treated as a different request.
- `POST .../chats/{chatId}/act` needs either an `Idempotency-Key` header or a `requestId` in the body.

## Errors

Errors are [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem documents sent as `application/problem+json`, with a machine-readable `code`, a `requestId` and often a `hint`. Match on `code`, never on the wording of `detail`.

```
{
   "type" :  "https://api.jetstack.ai/errors/api-key-insufficient-scope" ,
   "title" :  "Insufficient Permissions" ,
   "status" :  403 ,
   "detail" :  "Missing required scope: projects:deploy" ,
   "instance" :  "/v1/projects/prj_8Hq2xL0vT3/assets/ast_31/retire" ,
   "code" :  "API_KEY_INSUFFICIENT_SCOPE" ,
   "requestId" :  "req_7f3a9c2e" ,
   "hint" :  "Mint a key that carries `projects:deploy`. Projects scopes are never implied by other scopes, and `projects:deploy` / `projects:billing` are excluded from every preset."
}
```

The status tells you what kind of problem it is:

| Status | Meaning                                                                                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The request is invalid. `detail` names the field.                                                                                                                               |
| `401`  | The API key is missing, unknown, revoked or expired.                                                                                                                            |
| `402`  | Not enough credits (`INSUFFICIENT_PROJECT_CREDITS`).                                                                                                                            |
| `403`  | The key lacks the scope (`API_KEY_INSUFFICIENT_SCOPE`), the creator’s role lacks the capability (`AUTH_PERMISSION_DENIED`), or Projects isn’t enabled (`PROJECTS_NOT_ENABLED`). |
| `404`  | No such project or item in your organization, or no such endpoint.                                                                                                              |
| `405`  | The path exists but not for this method. The `Allow` header lists the methods it accepts.                                                                                       |
| `409`  | Someone changed the item since you read it, or another operation is in progress.                                                                                                |
| `429`  | Rate limit reached. Wait for the seconds in `Retry-After`.                                                                                                                      |
| `503`  | Jetstack couldn’t confirm the key creator’s role. Retry shortly.                                                                                                                |

The refusal codes you are most likely to handle:

| Code                               | What to do                                                                                                       |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `PROJECTS_NOT_ENABLED`             | Projects isn’t on for your organization. See [Getting Access](https://jetstack.ai/docs/projects/getting-access). |
| `PORTAL_NOT_FOUND`                 | The portal isn’t connected to your organization.                                                                 |
| `PROJECT_PORTAL_ALREADY_BOUND`     | The project already has a portal. Create a new project for a different portal.                                   |
| `KNOWLEDGE_NOT_COMPILED`           | There is no published brief yet. Upload a document or chat first.                                                |
| `KNOWLEDGE_VERSION_CONFLICT`       | The decision changed since you read it. Read it again and retry.                                                 |
| `KNOWLEDGE_RESOLUTION_NOT_ALLOWED` | That resolution isn’t one this decision allows. Use one from its list.                                           |
| `BLUEPRINT_NOT_DERIVABLE`          | The blueprint can’t be derived yet. Check `cannotDeriveBecause` on `GET .../blueprint`.                          |
| `INSUFFICIENT_PROJECT_CREDITS`     | Add credits, then retry or resume the run.                                                                       |
| `RUN_NOT_PAUSED`                   | The run isn’t in a credit pause, so there is nothing to resume.                                                  |
| `PROJECT_OPERATION_IN_FLIGHT`      | Another operation is running on this asset. Wait for it to finish.                                               |
| `ASSET_PRECONDITION_FAILED`        | The asset isn’t in a state that allows this action.                                                              |
| `ASSET_CONFIRMATION_REQUIRED`      | Removing an asset from the portal needs `confirmationName` set to its exact name.                                |
| `ASSET_EXTENSION_REQUIRED`         | This action needs the Chrome extension with the client’s portal open.                                            |

Some outcomes aren’t errors because they aren’t your mistake. Deriving a blueprint while one is already running, for example, returns `200` with `skipped: true`, a `code` and a `reason`. A refused card action returns `ok: false` with a `refusal`.

## Full Reference

The [API reference](https://jetstack.ai/api) lists every Projects endpoint, grouped by area: access and credits, projects, members, portal, documents and operations, Knowledge, chats, blueprint, runs and the deploy log, and assets. Each one shows its scope, the role capability it needs, whether it accepts an `Idempotency-Key`, and its refusal codes. The same document is served live at `GET /v1/projects/openapi.json`, generated from the routes the API actually serves.

## Next Steps

[API reference ](https://jetstack.ai/api)Every Projects endpoint, with parameters, scopes and refusal codes.

[Authentication ](https://jetstack.ai/docs/developers/authentication)API keys, scopes, instance routing and rate limits.

[Projects Overview ](https://jetstack.ai/docs/projects)Chats, cards and receipts: how Projects works in the app.

[Chats & Cards ](https://jetstack.ai/docs/projects/chats)What each card does and what approving it changes.
