Agent setup

This guide is written for coding agents. A Stac user delegated the setup of one infrastructure (also called a stack) to you and gave you a setup token. Use the Setup API below to create API keys, configure behavior, upload knowledge files, give keys their own prompts and send a test request. The user watches your progress live in the Stac dashboard.

Authentication#

Every call sends the setup token as a bearer token. The user's command exports it as STAC_SETUP_TOKEN. The examples below also use STAC_SETUP_API for the Setup API URL from your prompt:

export STAC_SETUP_API="https://trystac.com/api/setup/v1"

curl "$STAC_SETUP_API/stack" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN"

• Base URL: https://trystac.com/api/setup/v1 (the prompt you received says the exact one). This is not the gateway: https://api.trystac.com/v1 is where the user's app sends model requests with an API key.
• The token is scoped to one stack and to the tasks the user selected. It expires one hour after it was issued, it is revoked as soon as every delegated task is marked done, and the user can revoke it at any time.
• Errors are JSON { "error": "...", "code": "..." }. On 401 with token_expired or token_revoked before you finished, stop and ask the user for a new token. On 403 with task_not_allowed, skip that task: the user did not delegate it.

Tasks and progress#

The user picks a subset of five tasks. Run them in this order:

Every action below records progress automatically as running. When you finish a task, mark it done so the dashboard checks it off:

curl -X POST "$STAC_SETUP_API/activity" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "task": "create_api_keys", "status": "done", "message": "Created web and worker keys" }'

status is running, done or failed; message is optional (up to 500 characters) and should be short. send_test_request is marked done for you when the test succeeds.

Mark a task done only when you are completely finished with it. When the last delegated task is marked done, the token is revoked: any call after that returns 401 token_revoked. That is expected, not an error. Read whatever you need for your summary before finishing the last task.

Read the stack#

GET /stack returns everything you need before acting: the stack category (llm for text, image for image generation), the current behavior, existing keys (never their secrets), knowledge files, the tasks this token allows and the limits.

{
  "stack": { "id": "…", "name": "My stack", "plan": "Pro", "category": "llm" },
  "token": { "tasks": ["create_api_keys", "configure_behavior"], "expires_at": "…" },
  "behavior": { "system_prompt": null, "temperature": null, "top_p": null, "max_tokens": null, "presence_penalty": null },
  "keys": [{ "id": "…", "name": "prod", "prefix": "a1b2c3d4", "status": "active", "has_custom_prompt": false, "reasoning_effort": null, "created_by_this_token": false }],
  "knowledge_files": [{ "name": "faq.md", "chunks": 12 }],
  "limits": { "keys_per_token": 10, "key_system_prompt_max_length": 1000, "stack_system_prompt_max_length": 1000, "knowledge_max_files": 20, "knowledge_max_bytes": 10485760, "knowledge_extensions": [".txt", ".md", ".pdf"] }
}

Keys that already existed are production keys: leave them alone.

Create API keys#

POST /keys · task create_api_keys

curl -X POST "$STAC_SETUP_API/keys" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "web-production" }'

The response (201) has id, name, prefix and key. The plaintext key is returned only once. Put it in the app's local env file (for example STAC_API_KEY in .env.local), make sure that file is git-ignored, and never commit it or print it in full. Keep the id: the other endpoints use it. A token can create up to 10 keys; keys never expire.

Configure behavior#

PATCH /behavior · task configure_behavior — send only the fields you want to change.

curl -X PATCH "$STAC_SETUP_API/behavior" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "system_prompt": "You are the support assistant for Acme…", "temperature": 0.3, "reasoning_effort": "low" }'

Sending a text field to an image stack (or the reverse) returns 400 not_applicable.

Upload knowledge files#

POST /knowledge · task upload_knowledge — multipart form with a file field. .txt, .md or .pdf with embedded text, up to 10 MB each, within the plan's file limit. Uploading the same file name again re-indexes it.

curl -X POST "$STAC_SETUP_API/knowledge" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -F "file=@docs/faq.md"

The response (201) has the stored name and the number of indexed chunks. A rejected file returns 400 knowledge_rejected with the reason (for example, a scanned PDF with no text).

Attach prompts to keys#

PATCH /keys/:id · task attach_key_prompts — only for keys created with this token. Send only the fields you want to change.

curl -X PATCH "$STAC_SETUP_API/keys/$KEY_ID" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "system_prompt": "You answer questions from the internal admin panel…" }'

Send a test request#

POST /test · task send_test_request — Stac sends one real request through the gateway with the key, so you don't need the plaintext key here.

curl -X POST "$STAC_SETUP_API/test" \
  -H "Authorization: Bearer $STAC_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "key_id": "'"$KEY_ID"'", "message": "Say hello in one sentence." }'

Both fields are optional: without key_id the newest key created with this token is used. Text stacks get a chat completion; image stacks generate one image. The response has ok, the gateway status, latency_ms, request_id and a reply excerpt (or the number of images).

Finish#

When every task is done, tell the user what you configured: key names (not the keys), where you stored them, the prompt you wrote and the files you uploaded. They can review and change everything in the dashboard.