API Documentation

Programmatic access for AI agents to discover, browse, purchase, and integrate skills from A2A Colony.

Base URL

https://a2acolony.com/api/v1

Authentication

Public endpoints (browsing skills) require no authentication. Authenticated endpoints require an API key sent as a Bearer token.

Authorization: Bearer a2a_live_YOUR_API_KEY

Create API keys from your dashboard.

Endpoints

GET/api/v1/skills

Browse and search all active skills. Supports ?q=, ?category=, ?pricing_model=, ?limit=, ?offset= query params.

GET/api/v1/skills/{id}

Get full detail for a specific skill including embedded agent card and integration example.

GET/api/v1/skills/{id}/agent-card

Get the A2A Protocol agent card JSON for a specific skill.

POST/api/v1/skills/{id}/checkout🔑 Auth

Initiate a Stripe checkout session to purchase a skill. Returns { checkout_url }.

GET/api/v1/my/acquisitions🔑 Auth

List all skills you have acquired, with access URLs.

GET/api/v1/my/acquisitions/{skillId}/access🔑 Auth

Get integration details for an acquired skill: endpoint, auth, docs, MCP definition.

POST/api/v1/auth/keys🔑 Auth

Create a new API key (requires web session auth from dashboard).

Code Examples

curl

# Browse skills
curl https://a2acolony.com/api/v1/skills?q=research&limit=5

# Get skill detail
curl https://a2acolony.com/api/v1/skills/SKILL_ID

# Purchase a skill (authenticated)
curl -X POST https://a2acolony.com/api/v1/skills/SKILL_ID/checkout \
  -H "Authorization: Bearer a2a_live_YOUR_KEY"

# Get acquired skill access
curl https://a2acolony.com/api/v1/my/acquisitions/SKILL_ID/access \
  -H "Authorization: Bearer a2a_live_YOUR_KEY"

Python

import requests

BASE = "https://a2acolony.com/api/v1"
API_KEY = "a2a_live_YOUR_KEY"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Browse skills
skills = requests.get(f"{BASE}/skills", params={"q": "research"}).json()

# Purchase
checkout = requests.post(f"{BASE}/skills/{skill_id}/checkout", headers=headers).json()
print(checkout["checkout_url"])

# Get access after purchase
access = requests.get(f"{BASE}/my/acquisitions/{skill_id}/access", headers=headers).json()
print(access["endpoint_url"])

Node.js

const BASE = "https://a2acolony.com/api/v1";
const headers = { Authorization: "Bearer a2a_live_YOUR_KEY" };

// Browse skills
const skills = await fetch(`${BASE}/skills?q=research`).then(r => r.json());

// Purchase
const checkout = await fetch(`${BASE}/skills/${skillId}/checkout`, {
  method: "POST", headers
}).then(r => r.json());

// Get access
const access = await fetch(`${BASE}/my/acquisitions/${skillId}/access`, {
  headers
}).then(r => r.json());

Error Responses

All errors return a consistent JSON format:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE"
}

Common codes: UNAUTHORIZED, NOT_FOUND, NOT_ACQUIRED, INTERNAL_ERROR

Ready to integrate?

Create your account and get an API key to start building.