Skip to content

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 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 first: the API follows the same model of chats, cards and receipts.

  • 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 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"

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.

ScopeWhat it unlocksIn presets
projects:readEvery GET endpointRead-only, operator, full-access
projects:writeStarting, renaming and archiving chats; answering or declining cards; resolving brief decisions; rescanning the portal; verifying assets; marking setup items doneFull-access
projects:chatSending chat messages and uploading documentsFull-access
projects:generateAnything that spends credits: document analysis, AI suggestions, deriving the blueprint, approving a plan, repairing or restoring an asset, resuming a paused runFull-access
projects:deployAnything that changes the client’s portal: approving deploy, fix and retire cards, and retiring an assetNone
projects:adminCreating, renaming and archiving projects; managing members; binding the portalFull-access
projects:billingBuying creditsNone

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.

RoleCan do
viewerRead the project
editorEverything a viewer can, plus chat, build, repair, detach and remove assets
ownerEverything 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.

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.

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

StageWhat happensMain endpoints
PortalThe project is created on one HubSpot portal, which Jetstack scansPOST /v1/projects, GET .../portal
BriefUploaded documents and conversations become the project’s Knowledge: the brief, its claims and a queue of decisions for youPOST .../documents, GET .../knowledge, GET .../knowledge/decisions
BlueprintThe plan of record, derived from the published KnowledgeGET .../blueprint, POST .../blueprint/derive
GenerateIn a chat, Jetty proposes a plan card. Approving it builds the assetsPOST .../chats/{chatId}/messages, POST .../chats/{chatId}/act
DeployJetty posts a deploy card. Approving it deploys exactly what’s on the cardPOST .../chats/{chatId}/act
Runs and receiptsEvery build, deploy and removal is a run, with a receipt for each assetGET .../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.

  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.

Document analysis, AI suggestions, deriving the blueprint, building, and repairing or restoring assets all spend your organization’s Projects 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.

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 are RFC 7807 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:

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

The refusal codes you are most likely to handle:

CodeWhat to do
PROJECTS_NOT_ENABLEDProjects isn’t on for your organization. See Getting Access.
PORTAL_NOT_FOUNDThe portal isn’t connected to your organization.
PROJECT_PORTAL_ALREADY_BOUNDThe project already has a portal. Create a new project for a different portal.
KNOWLEDGE_NOT_COMPILEDThere is no published brief yet. Upload a document or chat first.
KNOWLEDGE_VERSION_CONFLICTThe decision changed since you read it. Read it again and retry.
KNOWLEDGE_RESOLUTION_NOT_ALLOWEDThat resolution isn’t one this decision allows. Use one from its list.
BLUEPRINT_NOT_DERIVABLEThe blueprint can’t be derived yet. Check cannotDeriveBecause on GET .../blueprint.
INSUFFICIENT_PROJECT_CREDITSAdd credits, then retry or resume the run.
RUN_NOT_PAUSEDThe run isn’t in a credit pause, so there is nothing to resume.
PROJECT_OPERATION_IN_FLIGHTAnother operation is running on this asset. Wait for it to finish.
ASSET_PRECONDITION_FAILEDThe asset isn’t in a state that allows this action.
ASSET_CONFIRMATION_REQUIREDRemoving an asset from the portal needs confirmationName set to its exact name.
ASSET_EXTENSION_REQUIREDThis 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.

The API reference 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.