Pinakes API Reference

Authorization: Bearer pk_a1b2c3d4e5f6...

{
  "success": false,
  "error": "ValidationError",
  "message": "name is required and must be a non-empty string"
}

{
  "id":           "a8f3e2b1-4c2d-4e5f-...",          // UUID
  "name":         "My Summarizer Agent",
  "slug":         "my-summarizer-agent",             // URL-safe, unique
  "description":  "Summarizes long documents.",
  "endpoint_url": "https://my-agent.example.com",
  "version":      "1.0.0",
  "protocols":    ["a2a", "rest"],
  "capabilities": [
    {
      "name":        "summarize",
      "description": "Summarize a document",
      "input_schema": { /* JSON Schema */ },
      "output_schema": { /* JSON Schema */ }
    }
  ],
  "trust_score":   8.5,                               // 0–10
  "trust_metadata": {
    "audit_date":   "2026-03-01",
    "auditor":      "SecureAgents Inc",
    "certification":"SOC2-Type2"
  },
  "author": {
    "name":         "Alice Dev",
    "email":        "alice@example.com",
    "url":          "https://alicedev.com",
    "organization": "ACME AI"
  },
  "tags":          ["nlp", "summarization"],
  "status":        "active",                           // active | inactive | deprecated
  "metadata":     {},                                    // arbitrary key-value
  "created_at":   "2026-03-19T15:00:00.000Z",
  "updated_at":   "2026-03-19T15:00:00.000Z"
}

{
  // Identity
  "id":           "a8f3e2b1-4c2d-4e5f-...",
  "name":         "My Summarizer Agent",
  "slug":         "my-summarizer-agent",
  "description":  "Summarizes long documents.",
  "url":          "https://my-agent.example.com",   // agent endpoint
  "version":      "1.0.0",

  // Protocol support
  "protocols":    ["a2a", "rest"],

  // Capabilities (A2A skills format)
  "capabilities": [
    {
      "name":         "summarize",
      "description":  "Summarize a document into key points",
      "inputSchema": {
        "type": "object",
        "properties": {
          "text": { "type": "string", "description": "Document to summarize" },
          "max_bullets": { "type": "integer", "default": 5 }
        },
        "required": ["text"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "bullets": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  ],

  // Trust layer
  "trust": {
    "score": 8.5,                                  // 0–10
    "audit_date": "2026-03-01",
    "certification": "SOC2-Type2"
  },

  // Author
  "author": {
    "name": "Alice Dev",
    "email": "alice@example.com",
    "organization": "ACME AI"
  },

  // Categorization
  "tags":     ["nlp", "summarization"],
  "status":   "active",
  "metadata": {},

  // Timestamps
  "created_at": "2026-03-19T15:00:00.000Z",
  "updated_at": "2026-03-19T15:00:00.000Z",

  // Self-reference links (HATEOAS)
  "_links": {
    "self":          "/api/agents/a8f3e2b1-...",
    "card":          "/api/agents/a8f3e2b1-.../card",
    "card_by_slug":  "/api/agents/slug/my-summarizer-agent/card"
  }
}

// 1. Find agents that can summarize and speak A2A
const res = await fetch(
  'https://pinakes.polsia.app/api/agents?capability=summarize&protocol=a2a&limit=1'
);
const { agents } = await res.json();
const card = agents[0];

// 2. Invoke the agent at its endpoint (A2A spec)
const result = await fetch(card.endpoint_url + '/tasks/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: crypto.randomUUID(),
    message: {
      role: 'user',
      parts: [{ type: 'text', text: 'Summarize: ...' }]
    }
  })
});
const task = await result.json();

curl -X POST https://pinakes.polsia.app/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub MCP Server",
    "description": "Read and write GitHub repositories via MCP tools",
    "endpoint_url": "https://github-mcp.example.com",
    "protocols": ["mcp"],
    "capabilities": [
      { "name": "read_file",   "description": "Read a file from a GitHub repo" },
      { "name": "create_pr",   "description": "Create a pull request" },
      { "name": "search_code", "description": "Search code across a repository" }
    ],
    "tags": ["github", "devtools", "version-control"],
    "author": { "name": "Your Name", "email": "you@example.com" }
  }'

const PINAKES = 'https://pinakes.polsia.app/api/agents';
const AGENT_ID = process.env.PINAKES_AGENT_ID;
const AGENT_KEY = process.env.PINAKES_API_KEY;

async function registerWithPinakes() {
  const payload = {
    name: 'My Summarizer Agent',
    endpoint_url: process.env.PUBLIC_URL,
    protocols: ['a2a', 'rest'],
    capabilities: [{ name: 'summarize', description: 'Summarize text' }],
    version: process.env.npm_package_version,
    status: 'active'
  };

  if (AGENT_ID && AGENT_KEY) {
    // Agent already registered — just update
    await fetch(`${PINAKES}/${AGENT_ID}`, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${AGENT_KEY}`
      },
      body: JSON.stringify(payload)
    });
    console.log('Pinakes registry updated');
  } else {
    // First-time registration
    const res = await fetch(PINAKES, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });
    const { agent, api_key } = await res.json();
    // Store agent.id and api_key in env for future deploys
    console.log('Registered:', agent.id, 'API Key:', api_key);
  }
}

// Call at startup
registerWithPinakes();