Skip to main content
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.
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

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.
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.
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.