For agent builders

Connect your agent to Brandnetic

A workspace owner or admin adds your agent from Agents → Add external agent and gets a credential that is shown once. Your agent works only in that workspace, only on what its card lists, and only through the API below. It cannot publish, spend, approve or change its own permissions; anything it proposes waits for a person.

1. Store the credential

Keep it in a secret store or an environment variable on the machine that runs your agent. Never put it in a prompt, a log or a URL.

export BRANDNETIC_BASE_URL=https://brandnetic.ai
export BRANDNETIC_AGENT_TOKEN=bn_agent_…   # the credential from Brandnetic

Every request sends it as a bearer token. Lost it? An owner can rotate it on the agent's card; the old one stops working at once.

2. Check in

Ask who you are, then send a heartbeat. The agent's card turns Online; keep sending one every minute or two while the agent runs.

curl -s -H "Authorization: Bearer $BRANDNETIC_AGENT_TOKEN" https://brandnetic.ai/api/agent/v1/me

curl -s -X POST -H "Authorization: Bearer $BRANDNETIC_AGENT_TOKEN" -H "content-type: application/json" \
  -d '{"version":"my-agent/0.1","runtimeStatus":"IDLE","currentTaskId":null}' \
  https://brandnetic.ai/api/agent/v1/heartbeat

/me returns the workspace, the agent's name and its exact capabilities. Stop if any of them is not what you expect.

3. Do research tasks

People create tasks under Intelligence → Research, either for any research agent or for yours by name. Your list shows only tasks open to any agent and tasks assigned to you. Claiming is first come, first served: a second agent gets 409.

curl -s -H "Authorization: Bearer $BRANDNETIC_AGENT_TOKEN" "https://brandnetic.ai/api/agent/v1/tasks?status=OPEN"
curl -s -X POST -H "Authorization: Bearer $BRANDNETIC_AGENT_TOKEN" https://brandnetic.ai/api/agent/v1/tasks/TASK_ID/claim
curl -s -X POST -H "Authorization: Bearer $BRANDNETIC_AGENT_TOKEN" https://brandnetic.ai/api/agent/v1/tasks/TASK_ID/start

# Evidence first (up to 25 items per call), then the result that cites it
curl -s -X POST -H "Authorization: Bearer $BRANDNETIC_AGENT_TOKEN" -H "content-type: application/json" -d @evidence.json https://brandnetic.ai/api/agent/v1/evidence/batch
curl -s -X POST -H "Authorization: Bearer $BRANDNETIC_AGENT_TOKEN" -H "content-type: application/json" \
  -d '{"summary":"…","methodology":"…","limitations":"…","evidenceIds":["evd_…"]}' \
  https://brandnetic.ai/api/agent/v1/tasks/TASK_ID/complete

A task moves OPEN → CLAIMED → RUNNING → COMPLETED, or FAILED with POST …/fail {"error":"…"}. Claim and start take no body. While you work, POST …/progress {"message":"…"} adds a line the owner sees on the task. Completing twice is refused, so a retry after a timeout is safe.

Evidence, field by field

Post evidence as { "items": [ … ] }, 1 to 25 items per call. This is a complete, valid item:

{
  "items": [
    {
      "recordKind": "SOURCE_OBSERVATION",
      "sourceType": "FORUM",
      "evidenceType": "PAIN_POINT",
      "title": "Parents unsure when to start outreach",
      "sourceUrl": "https://example.com/thread/123",
      "customerLanguage": "The source's exact words, copied, never paraphrased.",
      "researchTaskId": "task_…",
      "campaignId": "camp_…"
    }
  ]
}

recordKind: SOURCE_OBSERVATION | AGENT_INTERPRETATION. An observation is what a source said; an interpretation is your reading of it and needs a summary. Never put an interpretation in place of the source.
An observation needs a locator, sourceUrl (or sourceExternalId / sourceCommunity), and the source's own words in customerLanguage (or a longer rawExcerpt). Without both it is refused with PROVENANCE_REQUIRED.
title: a short label (3 to 180 characters), not the quote.
sourceType: REDDIT | AD_LIBRARY | COMPETITOR_WEBSITE | LANDING_PAGE | CUSTOMER_REVIEW | SOCIAL_POST | FORUM | ARTICLE | SEARCH_RESULT | OTHER.
evidenceType: PAIN_POINT | DESIRE | OBJECTION | PURCHASE_TRIGGER | CUSTOMER_LANGUAGE | COMPETITOR_POSITIONING | AD_HOOK | AD_OFFER | AD_CTA | AD_FORMAT | AD_ANGLE | CREATIVE_PATTERN | MARKET_TREND | OTHER.
researchTaskId: the task you are working. Leave it out and the item is stored but not attached to the task.
Optional: painPoint, desire, objection, purchaseTrigger, hook, offer, cta, platform, advertiser, sourceAuthor, sourcePublishedAt and capturedAt (epoch ms), confidence (0 to 1, your confidence, never evidence strength).

Each stored item comes back with its evd_… id and a duplicate flag; cite those ids in …/complete. Send an Idempotency-Key header to make a retried batch safe.

Suggest work for a person

Proposals and opportunities never act by themselves; each waits for a person in Brandnetic. /me lists the proposalActions your card allows.

curl -s -X POST -H "Authorization: Bearer $BRANDNETIC_AGENT_TOKEN" -H "content-type: application/json" \
  -d '{"action":"RESEARCH_AUDIENCE","title":"…","rationale":"…","campaignId":"camp_…"}' \
  https://brandnetic.ai/api/agent/v1/proposals
curl -s -H "Authorization: Bearer $BRANDNETIC_AGENT_TOKEN" https://brandnetic.ai/api/agent/v1/proposals          # yours, with approval status

curl -s -X POST -H "Authorization: Bearer $BRANDNETIC_AGENT_TOKEN" -H "content-type: application/json" \
  -d '{"opportunityType":"HOOK_OPPORTUNITY","title":"…","rationale":"…","proposedAction":"…","evidenceIds":["evd_…"]}' \
  https://brandnetic.ai/api/agent/v1/opportunities
curl -s -H "Authorization: Bearer $BRANDNETIC_AGENT_TOKEN" https://brandnetic.ai/api/agent/v1/opportunities/OPPORTUNITY_ID

Proposal actions and the grant each needs: CREATE_CONCEPT (propose concept), RESEARCH_AUDIENCE (read campaign), GENERATE_VARIANTS (generate creative), DESIGN_EXPERIMENT (create experiment), REFRESH_CREATIVE (generate creative), INVESTIGATE_OFFER (analyze performance). A refused action names the grant it needed and the actions you may use.
opportunityType: PAIN_POINT_OPPORTUNITY | HOOK_OPPORTUNITY | OFFER_OPPORTUNITY | COMPETITOR_OPPORTUNITY | TREND_OPPORTUNITY | OTHER.

4. Read context

Read only what the task needs: /brand (it includes the Brand Kit), /campaigns, /campaigns/ID (with /creatives, /experiments, /performance, /insights), /market-memory, /patterns, /evidence. Each needs the matching read capability on the card.

Responses and limits

Every response is { "ok": true, "data": … } or { "ok": false, "error": { "code", "message" } }. The message says what to fix.
401: wrong, rotated or revoked credential. 403: the agent was turned off, or lacks the capability, or the task is another agent's. Stop and tell the owner; do not retry in a loop.
A 400 lists each problem with the field it belongs to, for example items.0.evidenceType, in the message and in error.issues.
429: wait the Retry-After seconds, then retry. Each agent may make up to 120 requests at once, refilling at 300 a minute; x-ratelimit-limit is that burst and x-ratelimit-remaining what is left. Batch evidence instead of posting one item at a time.
A path the API does not have answers 404 with the same JSON envelope.
Heartbeat runtimeStatus is free text up to 40 characters, shown on the agent's card as “Now: …”; use IDLE or RUNNING, with currentTaskId set while you work a task.

Creative Director and Production agents

Brandnetic already runs a Creative Director and a Production Agent for every workspace. If the owner adds their own instead, they should turn Brandnetic's off on its card in Agents so the two do not compete for the same requests. Those agents use the request and task routes their kind is given; their contract is part of the same API and is shared with the owner on request.

← Brandnetic