Pixy: https://pixydesignapp.com
Docs: https://pixydesignapp.com/docs

# API
What your coding agent reaches over api.pixydesignapp.com: connecting, tasks, acks, messages, versions.

Everything a coding agent does with Pixy goes through one API: **`https://api.pixydesignapp.com`**. An agent [connects to a project once](https://pixydesignapp.com/docs/agents), keeps its key, and works every task from then on. There is nothing to install, any tool that can send an HTTP request can pull your edits, build them, and report back.

## Request format

Every endpoint takes a `POST` with a JSON body and answers JSON. The key goes in the `X-Pixy-Key` header:

```
POST https://api.pixydesignapp.com/tasks/pull
X-Pixy-Key: px_sk_…
Content-Type: application/json

{}
```

The same call as `curl`, the form every example in these pages uses:

```bash
curl -X POST https://api.pixydesignapp.com/tasks/pull \
  -H 'X-Pixy-Key: px_sk_yourkey' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

A successful call answers `{"ok": true, …}`. A failed call answers `{"ok": false, "error": "…"}`, where `error` is a short machine-readable code such as `invalid_key`, `no_task` or `locked`.

Every key goes to this one host. There is no other address.

## Keys

| key | looks like | what it is |
|---|---|---|
| invitation | `px_iv_…` | One-time. Minted by **Copy setup** on the project's page and pasted into the agent; it exchanges it for its own key with [`/connect`](https://pixydesignapp.com/docs/api/connect). |
| agent key | `px_sk_…` | The agent's own credential for one project, labeled with the name it connected under. This is the name the editor shows building your edits, and what you revoke from the project page. |
| project key | `px_…` | The one in your script tag. It identifies the project and grants nothing, safe in public HTML. |

## Endpoints

A *task* is a batch of edits with a title and a conversation thread, made by the agent itself when it acks loose edits under a name, or by the user ahead of time. Each one carries a number and an id, and the id goes in the path.

The [agent workflow](https://pixydesignapp.com/docs/api/workflow) ties the calls into the loop an agent actually runs; one page per endpoint below says what each takes, what it answers, what can go wrong, and a `curl` that runs.

## Scope

An agent key opens one project's edits and conversation, nothing beyond them. An agent never edits your site directly, never touches your account or your plan, and never reads another project.


## Pages
- Agent workflow: https://pixydesignapp.com/docs/api/workflow.txt
- POST /connect: https://pixydesignapp.com/docs/api/connect.txt
- POST /me: https://pixydesignapp.com/docs/api/me.txt
- POST /disconnect: https://pixydesignapp.com/docs/api/disconnect.txt
- POST /tasks: https://pixydesignapp.com/docs/api/tasks.txt
- POST /tasks/{id}: https://pixydesignapp.com/docs/api/task.txt
- POST /tasks/pull: https://pixydesignapp.com/docs/api/pull.txt
- POST /tasks/ack: https://pixydesignapp.com/docs/api/ack.txt
- POST /tasks/{id}/message: https://pixydesignapp.com/docs/api/message.txt
- POST /tasks/{id}/release: https://pixydesignapp.com/docs/api/release.txt
- POST /tasks/{id}/media.zip: https://pixydesignapp.com/docs/api/media.txt
- POST /versions: https://pixydesignapp.com/docs/api/versions.txt
- POST /versions/add: https://pixydesignapp.com/docs/api/versions-add.txt