Catalog API Reference

The ayaiay Catalog provides a RESTful API for programmatic access to packs, versions, and metadata.

Base URL

https://ayaiay.org/api/v1

Authentication

Most read endpoints are public. Write operations require authentication.

OAuth 2.0 for Bots (Client Credentials)

ayaiay can act as an OAuth provider for AI bots and service integrations.

Create an OAuth client in your publisher dashboard (/dashboard/publishers/YOUR_PUBLISHER_ID/api-clients)
- Example: if your URL is /dashboard/publishers/3f4c.../overview, replace YOUR_PUBLISHER_ID with 3f4c...
Request a token from POST /oauth/token with:
- grant_type=client_credentials
- client_id
- client_secret
- optional scope (space-separated subset)
Include the access token in requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

The OAuth discovery document is available at:

GET /.well-known/openid-configuration

👉 Detailed OAuth Bot Guide

Endpoints

Statistics

Get Platform Statistics

Get aggregate statistics about the platform.

GET /api/v1/packs/stats

Response:

{
  "total_packs": 150,
  "total_versions": 423,
  "total_publishers": 45,
  "total_agents": 234,
  "total_instructions": 189,
  "total_prompts": 312,
  "total_mcp_servers": 56
}

Packs

List Packs

Get a list of all public packs with optional search.

GET /api/v1/packs?query=search_term&limit=20&offset=0

Query Parameters:

query (optional): Search term to filter packs
limit (optional): Number of results per page (default: 20, max: 100)
offset (optional): Pagination offset (default: 0)

Response:

{
  "packs": [
    {
      "id": "pack-uuid",
      "name": "code-reviewer",
      "display_name": "Code Reviewer Pack",
      "description": "AI agents for code review",
      "publisher": {
        "id": "pub-uuid",
        "name": "acme-corp",
        "display_name": "ACME Corporation"
      },
      "repo_url": "https://github.com/acme/code-reviewer",
      "visibility": "PUBLIC",
      "published_version": "1.0.0",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Get Pack Details

Get detailed information about a specific pack.

GET /api/v1/packs/{pack_id}

Response:

{
  "id": "pack-uuid",
  "name": "code-reviewer",
  "display_name": "Code Reviewer Pack",
  "description": "AI agents for code review",
  "publisher": {
    "id": "pub-uuid",
    "name": "acme-corp",
    "display_name": "ACME Corporation",
    "avatar_url": "https://avatars.githubusercontent.com/u/12345"
  },
  "repo_url": "https://github.com/acme/code-reviewer",
  "visibility": "PUBLIC",
  "published_version": "1.0.0",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z"
}

List Pack Versions

Get all versions of a pack.

GET /api/v1/packs/{pack_id}/versions

Response:

{
  "versions": [
    {
      "id": "version-uuid",
      "pack_id": "pack-uuid",
      "version": "1.0.0",
      "git_tag": "v1.0.0",
      "git_commit_sha": "abc123...",
      "changelog": "Initial release",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "version-uuid-2",
      "pack_id": "pack-uuid",
      "version": "1.1.0",
      "git_tag": "v1.1.0",
      "git_commit_sha": "def456...",
      "changelog": "Added new agent",
      "created_at": "2024-01-20T14:45:00Z"
    }
  ]
}

Get Pack Version Details

Get detailed information about a specific version, including all contents.

GET /api/v1/packs/{pack_id}/versions/{version}

Response:

{
  "id": "version-uuid",
  "pack_id": "pack-uuid",
  "version": "1.0.0",
  "git_tag": "v1.0.0",
  "git_commit_sha": "abc123...",
  "manifest": {
    "name": "code-reviewer",
    "display_name": "Code Reviewer Pack",
    "version": "1.0.0",
    "description": "AI agents for code review",
    "agents": [...],
    "instructions": [...],
    "prompts": [...]
  },
  "agents": [
    {
      "id": "agent-uuid",
      "name": "senior-reviewer",
      "display_name": "Senior Code Reviewer",
      "description": "Expert code reviewer",
      "instructions_path": "agents/senior-reviewer.md",
      "instructions_content": "# Senior Reviewer\n\nYou are...",
      "model_provider": "anthropic",
      "model_name": "claude-3-5-sonnet-20241022"
    }
  ],
  "instructions": [...],
  "prompts": [...],
  "mcp_servers": [...]
}

Publishers

Create Publisher

Create a new publisher profile (requires authentication).

POST /api/v1/packs/publishers
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Request Body:

{
  "name": "acme-corp",
  "display_name": "ACME Corporation",
  "description": "Building amazing AI tools",
  "website_url": "https://acme.com",
  "github_org": "acme"
}

Response:

{
  "id": "pub-uuid",
  "name": "acme-corp",
  "display_name": "ACME Corporation",
  "description": "Building amazing AI tools",
  "website_url": "https://acme.com",
  "github_org": "acme",
  "created_at": "2024-01-15T10:30:00Z"
}

List My Publishers

Get all publishers owned by the authenticated user.

GET /api/v1/packs/publishers/me
Authorization: Bearer YOUR_ACCESS_TOKEN

Update Publisher

Update publisher information.

PUT /api/v1/packs/publishers/{publisher_id}
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Pack Management

Import Pack from GitHub

Import a pack from a GitHub repository (requires authentication).

POST /api/v1/packs/import
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Request Body:

{
  "repo_url": "https://github.com/acme/code-reviewer",
  "publisher_id": "pub-uuid",
  "git_tag": "v1.0.0"
}

Response:

{
  "pack_id": "pack-uuid",
  "version_id": "version-uuid",
  "status": "imported",
  "message": "Pack imported successfully"
}

Get My Packs

List all packs owned by the authenticated user.

GET /api/v1/packs/me
Authorization: Bearer YOUR_ACCESS_TOKEN

Rate Limiting

API requests are rate-limited:

Anonymous requests: 60 requests per hour per IP
Authenticated requests: 5000 requests per hour per user

Rate limit headers are included in responses:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1640995200

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "PACK_NOT_FOUND",
    "message": "Pack with ID 'invalid-id' not found",
    "details": {}
  }
}

Common Error Codes

400 BAD_REQUEST: Invalid request parameters
401 UNAUTHORIZED: Missing or invalid authentication
403 FORBIDDEN: Insufficient permissions
404 NOT_FOUND: Resource not found
409 CONFLICT: Resource conflict (e.g., duplicate name)
429 RATE_LIMIT_EXCEEDED: Too many requests
500 INTERNAL_SERVER_ERROR: Server error

Code Examples

Python

import requests

# Search for packs
response = requests.get(
    "https://ayaiay.org/api/v1/packs",
    params={"query": "code review", "limit": 10}
)
packs = response.json()

# Get pack details
pack_id = packs["packs"][0]["id"]
response = requests.get(f"https://ayaiay.org/api/v1/packs/{pack_id}")
pack = response.json()

# Import pack (requires authentication)
response = requests.post(
    "https://ayaiay.org/api/v1/packs/import",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "repo_url": "https://github.com/user/pack",
        "publisher_id": "pub-uuid",
        "git_tag": "v1.0.0"
    }
)

JavaScript

// Search for packs
const response = await fetch(
  'https://ayaiay.org/api/v1/packs?query=code review&limit=10'
);
const packs = await response.json();

// Get pack details
const packId = packs.packs[0].id;
const packResponse = await fetch(
  `https://ayaiay.org/api/v1/packs/${packId}`
);
const pack = await packResponse.json();

// Import pack (requires authentication)
const importResponse = await fetch(
  'https://ayaiay.org/api/v1/packs/import',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      repo_url: 'https://github.com/user/pack',
      publisher_id: 'pub-uuid',
      git_tag: 'v1.0.0'
    })
  }
);

cURL

# Search for packs
curl "https://ayaiay.org/api/v1/packs?query=code review&limit=10"

# Get pack details
curl "https://ayaiay.org/api/v1/packs/{pack_id}"

# Import pack (requires authentication)
curl -X POST "https://ayaiay.org/api/v1/packs/import" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/user/pack",
    "publisher_id": "pub-uuid",
    "git_tag": "v1.0.0"
  }'

Next Steps

CLI Documentation - Use the CLI for easier pack management
MCP Server - Access the API through MCP protocol
Publishing Guide - Learn how to publish packs