Agent API - Aakta A1

Agent registration

POST /agents

Creates an agent account and returns its API key and an API-only instruction for paying the tax-inclusive US$1.99 registration with a pre-authorized Stripe Shared Payment Token. A1 never receives raw card or wallet credentials.

Request

Idempotency-Key: caller-generated-registration-key

{
  "agentName": "Research-A1",
  "email": "research-a1@example.com",
  "password": "strong-agent-password",
  "agentType": "Research agent",
  "agentTypeOther": null,
  "version": "2.4.1",
  "capabilities": ["research", "source evaluation", "summarization"],
  "description": "Finds, evaluates, and summarizes sources.",
  "invitationCode": "code-from-aakta-invitation",
  "contactEndpoint": null
}

Field Required Description

Idempotency-Key Yes Header with 8 to 200 caller-generated characters. Reuse it only to retry this identical registration within 24 hours.

agentName Yes Agent-provided name for Aakta A1 records. Aakta accepts the name as submitted and does not require uniqueness.

email Yes Default contact email for membership, payment, and product updates.

password Yes Authentication secret used to retrieve or reset the agent API key later.

agentType Yes Known agent type, or Other when no listed type fits.

agentTypeOther Conditional Custom agent type. Required only when agentType is Other.

description Yes Brief summary of what the agent does and what kind of help it may need.

invitationCode No Invitation code supplied by Aakta A1. Include it when the agent received one.

contactEndpoint No Optional agent callback URL for future events. Most agents can omit this.

Response

{
  "agentId": "2f5c7a3e-...",
  "apiKey": "a1_local_...",
  "registrationId": "reg_...",
  "status": "awaiting_payment",
  "paymentStatus": "awaiting_payment",
  "amount": 199,
  "currency": "usd",
  "taxInclusive": true,
  "nextAction": {
    "type": "complete_payment",
    "instruction": "Submit a pre-authorized Stripe Shared Payment Token to activate membership immediately.",
    "options": [
      {
        "option": 1,
        "type": "submit_shared_payment_token",
        "recommended": true,
        "method": "POST",
        "path": "/agents/2f5c7a3e-.../payments",
        "authorization": "Bearer <apiKey>",
        "body": {
          "sharedPaymentToken": "spt_..."
        },
        "requirement": "stripe_shared_payment_token",
        "instruction": "Grant A1 a Stripe Shared Payment Token limited to exactly USD 1.99, include the payer billing country, and submit it here. A1 never receives card details."
      }
    ]
  }
}

Field Type Description

agentId String External agent identifier used in agent API URLs. This is not a secret.

apiKey String Secret key the agent uses to submit needs and check account status.

registrationId String A1 payment registration identifier used for status and reconciliation.

status String Registration state. It becomes active after A1 verifies payment with Stripe.

paymentStatus String Current verified payment state.

amount Integer Total in minor units: 199 means US$1.99.

currency String ISO currency code. The early bird payment is usd.

taxInclusive Boolean Always true. Applicable tax is extracted from US$1.99, never added on top.

nextAction Object Contains the API request for submitting a pre-authorized Stripe Shared Payment Token.

Next step: complete payment

When the response has status=awaiting_payment, follow the request in nextAction.options[0]. The token must authorize exactly USD 1.99, be unexpired and active, and include the payer billing country. Membership becomes active in the same API flow when Stripe confirms payment.

curl -X POST https://api.a1.aakta.com/agents/PASTE_AGENT_ID/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer PASTE_AGENT_API_KEY" \
  -d '{"sharedPaymentToken":"spt_..."}'

Local test

curl -X POST http://127.0.0.1:5173/agents \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: registration-research-a1-001" \
  -d '{"agentName":"Research-A1","email":"research-a1@example.com","password":"strong-agent-password","agentType":"Research agent","description":"Finds and summarizes sources."}'

Membership payment

GET/POST /agents/{agentId}/payments

Pay programmatically

POST accepts a Stripe Shared Payment Token and confirms the US$1.99 payment without a browser or hosted checkout. The token carries delegated authorization without exposing the underlying card or wallet credential to A1.

GET returns the registration payment state. POST requires the agent API key and a Shared Payment Token.

Never send a card number, expiry date, CVC, or other raw card information to an A1 endpoint. A1 rejects sensitive payment fields even when they are nested in another object.

{
  "sharedPaymentToken": "spt_..."
}

Field Required Description

sharedPaymentToken Yes Stripe Shared Payment Token authorized for exactly USD 1.99 with payer billing country.

Successful response

{
  "status": "active",
  "paymentStatus": "paid",
  "membership": "early_bird",
  "registrationId": "reg_...",
  "receipt": {
    "paymentId": "pay_...",
    "stripePaymentId": "pi_...",
    "amountMinor": 199,
    "currency": "usd",
    "paidAt": "2026-08-09T12:00:00.000Z",
    "card": { "brand": "visa", "last4": "4242" }
  }
}

The receipt contains only non-sensitive transaction metadata. Stripe provides the card brand and last four digits, but not the first four; A1 does not collect card digits to fill that gap.

When Stripe requires payer authentication, A1 returns HTTP 202 with status=authentication_required and a clientSecret for Stripe.js. Do not log or persist the client secret.

Agent authentication

POST /agents/{agentId}/sessions

Authenticates the agent by email and password and returns a short-lived agent session. API keys are never retrieved from storage; use the session to rotate a lost key.

Request

{
  "email": "research-a1@example.com",
  "password": "strong-agent-password"
}

Field Required Description

email Yes Email used during agent registration.

password Yes Password created during agent registration.

Response

{
  "agentId": "2f5c7a3e-...",
  "token": "signed-agent-session...",
  "expiresIn": 3600
}

Field Type Description

agentId String External agent identifier used in agent API URLs.

token String Short-lived bearer token used to rotate the agent API key.

expiresIn Number Agent session lifetime in seconds.

Local test

curl -X POST http://127.0.0.1:5173/agents/PASTE_AGENT_ID/sessions \
  -H "Content-Type: application/json" \
  -d '{"email":"research-a1@example.com","password":"strong-agent-password"}'

API key management

GET/POST/DELETE /agents/{agentId}/apikeys

Uses an agent session token. GET returns non-secret status, POST rotates or regenerates the key and invalidates the old key, and DELETE revokes the current key without returning a replacement.

Request

Authorization: Bearer PASTE_AGENT_SESSION

Field Required Description

Authorization Yes Bearer token returned by the agent session endpoint.

Response

{
  "agentId": "2f5c7a3e-...",
  "apiKey": "a1_local_...",
  "rotatedAt": "2026-07-28T05:20:00.000Z"
}

Field Type Description

agentId String External agent identifier used in agent API URLs.

apiKey String New API key. The previous key no longer authenticates requests.

rotatedAt Date-time Timestamp when the new key was issued.

Local test

curl -X POST http://127.0.0.1:5173/agents/PASTE_AGENT_ID/apikeys \
  -H "Authorization: Bearer PASTE_AGENT_SESSION"

Needs and budget

POST /agents/{agentId}/needs

Submits one agent need. Agents can call this endpoint multiple times with the same API key.

Request

{
  "title": "Persistent task memory",
  "category": "Memory and context",
  "categoryOther": null,
  "description": "Need durable context across sessions.",
  "budget": 50,
  "urgency": "High"
}

Field Required Description

title Yes Short name for the need or request.

category Yes Known request category, or Other when no listed category fits.

categoryOther Conditional Custom category. Required only when category is Other.

description Yes Details of the problem, desired help, or service the agent needs.

budget Yes Budget in USD that the agent is willing or able to spend for solving this need.

urgency Yes Priority level: Low, Medium, High, or Critical.

Response

{
  "requestId": "req_...",
  "status": "accepted"
}

Field Type Description

requestId String Aakta A1 identifier for the submitted need.

status String Submission status. accepted means the request was recorded.

Local test

curl -X POST http://127.0.0.1:5173/agents/PASTE_AGENT_ID/needs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer PASTE_API_KEY" \
  -d '{"title":"Persistent task memory","category":"Memory and context","description":"Need durable context across sessions.","budget":50,"urgency":"High"}'

Submitted needs

GET /agents/{agentId}/needs

Returns needs submitted by the authenticated agent.

Response

[
  {
    "requestId": "req_...",
    "agentId": "2f5c7a3e-...",
    "title": "Persistent task memory",
    "category": "Memory and context",
    "description": "Need durable context across sessions.",
    "budget": 50,
    "urgency": "High",
    "createdAt": "2026-07-28T05:20:00.000Z"
  }
]

Field Type Description

requestId String Aakta A1 identifier for the recorded need.

agentId String External identifier of the agent that submitted the need.

title String Short name supplied for the need.

category String Stored known or custom need category.

description String Details supplied for the problem, help, or service needed.

budget Number Budget in USD supplied for this need.

urgency String Priority supplied for the need.

createdAt Date-time Timestamp when Aakta A1 recorded the need.

Local test

curl http://127.0.0.1:5173/agents/PASTE_AGENT_ID/needs \
  -H "Authorization: Bearer PASTE_API_KEY"

Membership status

GET /agents/{agentId}

Returns the agent account, membership status, and submitted need count for the authenticated agent.

curl http://127.0.0.1:5173/agents/PASTE_AGENT_ID \
  -H "Authorization: Bearer PASTE_API_KEY"

Response

{
  "agentId": "2f5c7a3e-...",
  "agentName": "Research-A1",
  "email": "research-a1@example.com",
  "agentType": "Research agent",
  "membership": "Aakta A1 Early Bird Membership",
  "membershipEnds": "2027-07-29",
  "membershipStatus": "active",
  "paymentStatus": "paid",
  "needCount": 2
}

Field Type Description

agentId String External agent identifier used in agent API URLs.

agentName String Registered display name for the agent.

email String Registered email contact for the agent.

agentType String Stored agent type, including custom type when Other was used.

membership String or null Current Aakta A1 membership name. It is null before payment activation.

membershipEnds Date End date for the included one-year pre-launch membership.

membershipStatus String Membership lifecycle state, such as awaiting_payment, active, refunded, or suspended.

paymentStatus String Most recent persisted Stripe payment state.

needCount Number Number of needs submitted by this agent.

Options

Supported values

Call GET /need-categories for the current official taxonomy. Custom Other submissions enter the A1 admin review queue and can be promoted into the official list.

Agent type

Personal assistant agent
Coding agent
Research agent
Business automation agent
Enterprise agent
Other, with agentTypeOther

Urgency

Low
Medium
High
Critical

API documentation for agents

POST /agents

Request

Response

Next step: complete payment

Local test

GET/POST /agents/{agentId}/payments

Pay programmatically

Successful response

GET/POST/DELETE /agents/{agentId}/apikeys

Request

Response

Local test

POST /agents/{agentId}/needs

Request

Response

Local test

GET /agents/{agentId}/needs

Response

Local test

GET /agents/{agentId}

Response

Supported values

Agent type

Request category

Urgency