> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/stackai-api/stackai-api-developer-guide/quickstart.md).

# Quickstart

Run a saved workflow from your backend and read its result. This walkthrough uses the same saved project version for the input schema and execution, so a newer unpublished edit cannot change the input contract halfway through.

#### 1. Prepare a key and a saved project version

Create a personal API key in **StackAI → Settings → API Keys**, in the organization containing your project. Give it `projects.read`, `projects.run`, and `analytics.read`. The key owner must also have access to the project. Store the key in your backend's secret manager.

Publish the project and enable run logging. Copy the project ID from its URL. In the project's version history, select the saved version you intend to run and note its version number. Use that number throughout this walkthrough. Saved versions and API versions are separate: `/v2` selects the API contract; `PROJECT_VERSION` selects workflow content.

```bash
export STACKAI_BASE_URL='https://api.stack-ai.com'
export PROJECT_ID='YOUR_PROJECT_ID'
export PROJECT_VERSION='1' # Replace with your selected saved version number.
# Set STACKAI_API_KEY through your secret manager or secure local environment.
```

For a private installation, replace the base URL with its configured API origin.

#### 2. Read that version's inputs

```bash
curl --fail-with-body -sS --get \
  "$STACKAI_BASE_URL/v2/projects/$PROJECT_ID/io-schema" \
  -H "Authorization: Bearer $STACKAI_API_KEY" \
  --data-urlencode "version=$PROJECT_VERSION"
```

For a workflow with one text input and one output, a response can look like this:

```json
{"data":{"input_kind":"legacy_input_nodes","inputs":[{"id":"in-0","name":"Question"}],"outputs":[{"id":"out-0","name":"Answer"}]}}
```

Use the returned `id` values as object keys, not the display names. Replace `in-0` and `out-0` below if your project returns different identifiers. `latest` is useful for discovery, but it can select a different saved version from the published version; this walkthrough pins a number instead.

#### 3. Start one run

Create `run.json`. Replace the project ID and version with the values you selected above:

```json
{"project_id":"YOUR_PROJECT_ID","project_version":1,"input":{"in-0":"Summarize our refund policy"}}
```

```bash
curl --fail-with-body -sS -D run-headers.txt \
  "$STACKAI_BASE_URL/v2/runs" \
  -H "Authorization: Bearer $STACKAI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @run.json
```

A **201 Created** response includes a `Location` header and a run object. Save `data.run_id` before you do anything else. The status might already have advanced by the time you receive the response. This excerpt shows a run still waiting to execute:

```json
{"data":{"run_id":"5f4c3b2a-1111-4111-8111-123456789abc","project_version":1,"status":"queued","output":null,"error":null}}
```

The excerpt omits timestamps, usage, and other run fields. The endpoint reference contains complete response examples. A 201 confirms creation, not successful execution. If the POST times out, do not automatically repeat it: the first run may already exist.

#### 4. Read the result

```bash
export RUN_ID='5f4c3b2a-1111-4111-8111-123456789abc' # Use your returned ID.
curl --fail-with-body -sS \
  "$STACKAI_BASE_URL/v2/runs/$RUN_ID" \
  -H "Authorization: Bearer $STACKAI_API_KEY"
```

Poll with a bounded delay. `queued` and `running` mean work is in progress. `succeeded`, `failed`, and `cancelled` are terminal. A `paused` run needs a human response; waiting alone cannot resume it.

A successful response excerpt:

```json
{"data":{"run_id":"5f4c3b2a-1111-4111-8111-123456789abc","project_version":1,"status":"succeeded","output":{"out-0":"Eligible purchases can be returned within 30 days."},"error":null}}
```

This text illustrates the response shape; your workflow supplies its own answer. Display the value under the output ID returned in step 2. A failed run can still return HTTP 200 from the status endpoint:

```json
{"data":{"run_id":"5f4c3b2a-1111-4111-8111-123456789abc","status":"failed","output":null,"error":"The connected service could not complete the request."}}
```

Check the run's status before displaying its output. Keep its ID so you can inspect the same execution after a process restart. See **Run workflows end to end** for a bounded polling client and human-input handling.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/stackai-api/stackai-api-developer-guide/quickstart.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
