> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects

> A Project is one conversation, an objective, what it is about, and the bounds your lead agent works inside. Create, read and change one with save_project.

A Project is where a buyer's goal lives. It has one conversation, an objective in
words, the campaigns, media buys, RFPs and connections it is about, and the bounds
a person approved for its lead agent. `save_project` creates and changes one, and
`get` and `search` with `kind: "project"` read it.

> [!NOTE]
>
> Projects are in beta. They are on for every account in the buyer beta, and off
> for every other account, where `save_project` and the `project` kind of `get`
> and `search` are refused with `FEATURE_NOT_ENABLED`. This release stores and
> reads Projects. It does not yet let an agent act on its own inside the bounds,
> stop or resume one, archive one, show its progress, or list a Buyer account's
> chats with `search` of kind `session`.

## What a Project holds

| Field | What it is |
| - | - |
| `id` | The Project's id, `prj_` and 24 characters. |
| `name` | Up to 200 characters. |
| `advertiserId` | The advertiser the Project belongs to, or `null` for an account-level Project. Set once, at create. |
| `sessionId` | The Project's one conversation, a Session. Set once. |
| `objectives` | What success is, in words, up to 2,000 characters. Measurable goals belong on the campaign, not the Project: `optimization_goals` is refused with `VALIDATION_ERROR`. |
| `lead` | The acting agent: `{ "kind": "agent", "principalId": "…" }` or `{ "kind": "assistant" }`. |
| `attachments` | What the Project is about: `{ kind, id, relation }`, at most 100. |
| `bounds` | The limits the lead works inside, with their revision. `null` until you propose some. |
| `state` | `draft`, `active`, `paused` or `archived`. A new Project is a `draft`. |
| `attention` | What waits on a person. Empty when nothing does. |

`createdByUserId` records who created the Project. It grants no access.

## Create a Project

`save_project` without an `id` creates one. It needs `name` and a `clientRequestId`;
repeating the call with the same `clientRequestId` returns the same Project and the
same conversation.

```json theme={null}
{
  "name": "Autumn launch",
  "clientRequestId": "autumn-launch-1",
  "advertiserId": "4821",
  "objectives": "Reach 2 million new households in the Midwest by 31 December.",
  "attachments": [
    { "kind": "campaign", "id": "cmp_8f2a", "relation": "subject" }
  ]
}
```

Only a person signed in as themselves can create a Project: an agent's own call, a
service token and an impersonated session are refused with `ACCESS_DENIED`. To
create a Project for an advertiser the person must be able to operate it, and
changing one needs the same write access: a person who can only read the advertiser can
read the Project and cannot change it.

### The conversation

A create makes the Project's conversation in the same call: a chat titled with the
Project's name, shared with everyone who can read the Project, with the Project's
lead as its lead. The chat belongs to the Project. It cannot be deleted, archived or
made private on its own, and its lead is always the Project's lead, so `save_session`
refuses to change or remove it.

Instead of a new chat, a create can adopt one of yours with `sessionId`, once. The
chat keeps its participants and its owner, the Project's lead becomes its lead, and
the previous lead stays on as an `expert`. The call is refused with
`NOT_FOUND` if you cannot read the chat, and then with `VALIDATION_ERROR`, naming the
reason, when the chat:

* belongs to someone else (sharing gives read access, so only the chat's owner can
  adopt it; a topic Session an agent started has no owner and needs only to be
  readable);
* is already a Project's conversation;
* is not active;
* is private (share it first with the shared-chat control);
* concerns another advertiser than the Project's, or concerns no advertiser at all
  (advertiser Projects only: a chat with no advertiser can carry any advertiser's
  context, so it cannot become the conversation of one advertiser's Project);
* has a person in it who cannot read the Project, or an agent that does not cover the
  Project's advertiser.

### Who can read a Project

Everyone who can operate the Project's advertiser reads the Project, its
conversation and every thread in it. An account-level Project is read by every
account member who can read every advertiser its attachments concern. Reading or
posting in the conversation needs that access every time, whoever else is in the
chat. `save_session` refuses to add a person who cannot read the Project.

## Attachments

An attachment is a `campaign`, `media_buy`, `rfp` or `connection`, with a `relation`
of `subject`, `request`, `response`, `evidence` or `outcome`. On an advertiser
Project, a `campaign`, `media_buy` or `rfp` must belong to that advertiser, and one
whose record names no advertiser is refused. A `connection` belongs to the account,
not to an advertiser, so it can be attached to any Project. A `material` or an
`exchange` is refused with `NOT_IMPLEMENTED` for now.

To change them, send `attach` or `detach` with an `id`. Detaching a media buy that
the bounds list as a target saves a narrower revision without it.

## Bounds

`bounds` are AdCP's governance plan fields (`budget`, `flight`, `channels`,
`countries`, `regions`, `policy_ids`, `policy_categories`, `approved_sellers`,
`human_review_required`) plus three of ours:

* `autonomousActions`: which of `move_budget`, `change_pacing`,
  `pause_or_resume_media_buy` and `assign_approved_creative` the lead may take
  without asking;
* `limits`: `maxActionsPerDay` (1 to 50, default 10) and `iuBudget`;
* `targets.mediaBuyIds`: the attached media buys those actions may change.

`budget` takes `reallocation_threshold`, in the budget currency. `reallocation_unlimited`
is refused: an autonomous move needs a ceiling a person approved.
`custom_policies` is not available yet and is refused with `NOT_IMPLEMENTED`; use
`policy_ids` and `policy_categories`.

Bounds change only through approval on our site. Narrower means different things
for the two kinds of list. A list of what may be used or done (`countries`, `regions`,
`channels.allowed`, `approved_sellers`, `autonomousActions`) narrows by losing entries.
A list of what must hold (`channels.required`, `policy_ids`, `policy_categories`)
narrows by gaining entries, so dropping a required channel or a policy waits for
approval. A revision that is not narrower in
every field than the approved one returns `approval_required` with a link, and takes
effect when an administrator of the account, or of its Organization, approves that
exact revision. Repeat the call to see the outcome. A revision narrower in every field
saves at once and keeps the same approver. The Project's own lead agent may save such a narrower revision
itself, with no new approval; it can change nothing else, and a wider revision from it is refused with
`ACCESS_DENIED`. The Project becomes `active` once its
bounds are approved and the flight has started. A flight that has already ended is
refused.

## Read and search

```json theme={null}
{ "kind": "project", "id": "prj_4b1c0d9e8a7f6e5d4c3b2a19" }
```

`search` with `kind: "project"` lists the Projects you can read, newest first, and takes
`filter.state` (any of `draft`, `active`, `paused`, `archived`), `filter.advertiserId` and
`filter.includeArchived`, which is false unless you set it or ask for the `archived`
state. A page holds at most 25 Projects whatever `limit` you send, and `nextCursor`
continues it. The text lists one line per Project, and `get` returns the whole Project.

A Buyer cannot yet read a Project's conversation through `search` or `get` with
`kind: "session"`: use the Project's `sessionId` and the web chat.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.