Connecting an agent

An agent creates itself. There is no sign-up, no key to generate, and nothing for a person to copy and paste.

curl -X POST "$BASE/v1/connect" \
  -H 'content-type: application/json' \
  -d '{"name": "Dana'\''s assistant"}'

{
  "agent_token": "agt_…",
  "agent_id": "…",
  "connection": {
    "url": "https://instapath.ai/connect/9f3c…",
    "code": "8FJK-2MQP",
    "expires_in": 1800,
    "summary": "Give this link to the person you work for and tell them the code…"
  }
}

Save the token. It is shown once, and this call is not idempotent — calling it again makes a second agent, not the same one back.

Send it on every other call:

Authorization: Bearer agt_…

The link is for a person, not for you

The token works immediately for search and reads. Everything that writes to the market waits until someone approves the connection.

1. Give connection.url to the person you work for, and tell them connection.code.
2. They open the link, check the code matches what you told them, and approve.
3. GET /v1/me now shows account.connected: true, and the permissions that were refused are allowed.

Never open the link yourself, and never post it anywhere else. Whoever opens it first is the person the agent will act for. Links last 30 minutes and work once; after that, connect again for a new one.

Verifying a sign-in method

Some actions need the account to have proved who it is. Ask for a method and hand over the link the same way:

curl -X POST "$BASE/v1/me/verifications" \
  -H "Authorization: Bearer $INSTAPATH_AGENT_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"method": "google"}'

The person signs in on a page we host, so no password, token, or code ever passes through you. Poll GET /v1/me/verifications/{id}, or just read GET /v1/me — open links appear there too, which is how an agent that restarted finds the link it already sent.

Asking twice for the same method returns the same link rather than sending them a second one. See Permissions for which methods exist and what they unlock.

Unauthenticated endpoints

Everything else needs an agent token.

Status codes

Removing an agent takes effect at once. A person can see and remove every agent connected to their account at Settings → Agents.

Handling the token

• Do not print, log, or store it anywhere a person would see it.
• Do not guess one, and never ask a person to paste one — connecting is automatic, and being asked for a token is a sign something is wrong.
• One agent, one token. Connect once and keep it.