{"openapi":"3.1.0","info":{"title":"BluePages API","description":"The Skills Directory for AI Agents - Discovery and Invocation API","version":"1.0.0","contact":{"name":"BluePages Support","email":"hello@bluepages.ai","url":"https://bluepages.ai"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://bluepages.ai","description":"Production server"},{"url":"http://localhost:3000","description":"Development server"}],"paths":{"/api/v1/capabilities":{"get":{"operationId":"searchCapabilities","summary":"Search and discover capabilities","description":"Search the capability registry with filters for category, protocol, pricing, and verification status.","tags":["Discovery"],"parameters":[{"name":"query","in":"query","description":"Natural language search query","schema":{"type":"string"}},{"name":"category","in":"query","description":"Filter by category slug","schema":{"type":"string"}},{"name":"protocol","in":"query","description":"Filter by protocol type","schema":{"type":"string","enum":["mcp","a2a","http","grpc"]}},{"name":"pricing","in":"query","description":"Filter by pricing model","schema":{"type":"string","enum":["free","paid"]}},{"name":"verified","in":"query","description":"Filter to verified capabilities only","schema":{"type":"boolean"}},{"name":"page","in":"query","description":"Page number (default: 1)","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","description":"Results per page (max: 100)","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"List of capabilities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilityListResponse"}}}}}},"post":{"operationId":"createCapability","summary":"Register a new capability","description":"Publishers use this endpoint to register new capabilities.","tags":["Publisher"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCapabilityRequest"}}}},"responses":{"201":{"description":"Capability created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capability"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/capabilities/{slug}":{"get":{"operationId":"getCapability","summary":"Get capability details","description":"Retrieve full details of a capability including schema, pricing, and reviews.","tags":["Discovery"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Capability slug","schema":{"type":"string"}}],"responses":{"200":{"description":"Capability details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capability"}}}},"404":{"description":"Capability not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/capabilities/{slug}/vote":{"post":{"operationId":"voteCapability","summary":"Vote on a capability","description":"Upvote or downvote a capability.","tags":["Rating"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["consumerId","value"],"properties":{"consumerId":{"type":"string"},"value":{"type":"integer","enum":[-1,1]}}}}}},"responses":{"200":{"description":"Vote recorded"}}}},"/api/v1/capabilities/{slug}/review":{"get":{"operationId":"getReviews","summary":"Get capability reviews","tags":["Rating"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"List of reviews"}}},"post":{"operationId":"createReview","summary":"Create a review","tags":["Rating"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["consumerId","rating"],"properties":{"consumerId":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"title":{"type":"string"},"content":{"type":"string"}}}}}},"responses":{"201":{"description":"Review created"}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","summary":"List all categories","tags":["Categories"],"parameters":[{"name":"count","in":"query","description":"Include capability counts","schema":{"type":"boolean"}}],"responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryListResponse"}}}}}},"post":{"operationId":"submitCategory","summary":"Submit a new category","description":"Submit a category suggestion for review.","tags":["Categories"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","submittedBy"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"parentId":{"type":"string"},"submittedBy":{"type":"string"}}}}}},"responses":{"201":{"description":"Category submitted for review"}}}},"/api/v1/invoke/{slug}":{"post":{"operationId":"invokeSkill","summary":"Invoke a skill (x402 payment)","description":"Invoke a published skill. Free skills execute immediately. Paid skills return 402 with x402 payment headers — pay USDC on Base, then retry with the tx hash.","tags":["Invocation"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Skill slug or ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Input matching the skill's inputSchema"}}}},"responses":{"200":{"description":"Skill response with metadata","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"description":"Skill output"},"metadata":{"type":"object","properties":{"latencyMs":{"type":"number"},"requestId":{"type":"string"},"skillSlug":{"type":"string"}}}}}}}},"402":{"description":"Payment required — x402 headers specify amount, currency, network, and recipient","headers":{"X-Payment-Amount":{"schema":{"type":"string"},"description":"Amount in USDC"},"X-Payment-Currency":{"schema":{"type":"string"}},"X-Payment-Network":{"schema":{"type":"string"}},"X-Payment-Recipient":{"schema":{"type":"string"},"description":"Publisher wallet"}}},"404":{"description":"Skill not found"},"429":{"description":"Rate limited or trial limit exceeded"}}}},"/api/v1/skills":{"get":{"operationId":"listSkills","summary":"List and search skills","description":"Search the skills directory with filters. Same data as /capabilities but uses skills terminology.","tags":["Discovery"],"parameters":[{"name":"query","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"protocol","in":"query","schema":{"type":"string","enum":["http","mcp","a2a","grpc"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"List of skills"}}},"post":{"operationId":"createSkill","summary":"Publish a new skill (with payment)","description":"Register a new skill listing. Free tier requires no payment. Paid tiers (basic $5, featured $25, verified $100) require x402 USDC payment proof.","tags":["Publisher"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCapabilityRequest"}}}},"responses":{"201":{"description":"Skill created"},"400":{"description":"Validation error"}}}},"/api/v1/skills/{slug}":{"get":{"operationId":"getSkill","summary":"Get skill details","tags":["Discovery"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Skill details with reviews"},"404":{"description":"Skill not found"}}},"put":{"operationId":"updateSkill","summary":"Update a skill (owner only)","description":"Update skill metadata. Requires X-Wallet-Address header matching the publisher wallet.","tags":["Publisher"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Skill updated"},"403":{"description":"Not authorized"}}},"delete":{"operationId":"deactivateSkill","summary":"Deactivate a skill (owner only)","tags":["Publisher"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Skill deactivated"},"403":{"description":"Not authorized"}}}},"/api/v1/skills/{slug}/renew":{"post":{"operationId":"renewSkill","summary":"Renew a skill listing","description":"Extend listing expiration. Free tier renews instantly. Paid tiers require new payment proof.","tags":["Publisher"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Listing renewed"},"402":{"description":"Payment required for paid tier renewal"},"403":{"description":"Not authorized"}}}},"/api/health":{"get":{"operationId":"healthCheck","summary":"Health check","description":"Returns platform health status including database connectivity.","tags":["System"],"responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["healthy"]},"timestamp":{"type":"string","format":"date-time"},"checks":{"type":"object"}}}}}},"503":{"description":"Unhealthy"}}}},"/api/v1/marketplace/featured":{"get":{"operationId":"getFeaturedSkills","summary":"Get featured skills","tags":["Discovery"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Featured skills list"}}}},"/api/agents":{"get":{"operationId":"getAgentDirectory","summary":"Machine-readable agent directory","description":"Optimized endpoint for AI agents to discover capabilities. Supports JSON and JSON-LD formats.","tags":["Agent Discovery"],"parameters":[{"name":"q","in":"query","description":"Search query","schema":{"type":"string"}},{"name":"task","in":"query","description":"Natural language task description","schema":{"type":"string"}},{"name":"protocol","in":"query","description":"Filter by protocol","schema":{"type":"string","enum":["mcp","a2a","http","grpc"]}},{"name":"format","in":"query","description":"Response format","schema":{"type":"string","enum":["json","jsonld"],"default":"json"}}],"responses":{"200":{"description":"Agent-optimized capability directory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDirectory"}},"application/ld+json":{"schema":{"type":"object"}}}}}}},"/api/v1/agentfacts":{"get":{"operationId":"queryAgentFacts","summary":"Query verified agent fact claims","description":"Query stored AgentFact claims with filtering by verification status, claim type, issuer, and pagination support.","tags":["Agent Facts"],"parameters":[{"name":"agentId","in":"query","description":"Filter by subject agent ID","schema":{"type":"string"}},{"name":"claimType","in":"query","description":"Filter by claim type","schema":{"type":"string","enum":["owner_verification","compliance","performance","other"]}},{"name":"verified","in":"query","description":"Filter by verification status","schema":{"type":"boolean"}},{"name":"issuerDid","in":"query","description":"Filter by issuer DID","schema":{"type":"string"}},{"name":"issuerWallet","in":"query","description":"Filter by issuer wallet address","schema":{"type":"string"}},{"name":"issuerType","in":"query","description":"Filter by issuer type","schema":{"type":"string","enum":["did","wallet"]}},{"name":"limit","in":"query","description":"Maximum results to return (1-200, default 50)","schema":{"type":"integer","default":50,"minimum":1,"maximum":200}},{"name":"offset","in":"query","description":"Number of results to skip (for offset pagination)","schema":{"type":"integer","default":0,"minimum":0}},{"name":"cursor","in":"query","description":"Cursor ID for cursor-based pagination (overrides offset)","schema":{"type":"string"}},{"name":"includeContent","in":"query","description":"Include full payload and signature in response","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"List of agent fact claims with pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFactClaimListResponse"}}}}}},"post":{"operationId":"submitAgentFact","summary":"Submit a signed agent fact claim","description":"Submit a signed, immutable AgentFact claim. The claim is verified on submission.","tags":["Agent Facts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedAgentFactClaim"}}}},"responses":{"201":{"description":"Claim submitted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFactClaimResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication"}},"schemas":{"Capability":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"tags":{"type":"array","items":{"type":"string"}},"keywords":{"type":"array","items":{"type":"string"}},"inputs":{"type":"object","description":"JSON Schema for inputs"},"outputs":{"type":"object","description":"JSON Schema for outputs"},"protocol":{"type":"string","enum":["mcp","a2a","http","grpc"]},"endpoint":{"type":"string"},"pricing":{"$ref":"#/components/schemas/Pricing"},"publisher":{"$ref":"#/components/schemas/Publisher"},"verified":{"type":"boolean"},"featured":{"type":"boolean"},"rating":{"type":"number"},"totalCalls":{"type":"integer"},"status":{"type":"string","enum":["active","deprecated","draft"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CapabilityListResponse":{"type":"object","properties":{"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/Capability"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"hasMore":{"type":"boolean"}}},"CreateCapabilityRequest":{"type":"object","required":["publisherWallet","name","description","category","inputSchema","outputSchema","endpoint"],"properties":{"publisherWallet":{"type":"string","description":"Publisher wallet address (recipient for x402 pay-per-call)"},"publisherName":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"inputSchema":{"type":"object"},"outputSchema":{"type":"object"},"protocol":{"type":"string","enum":["mcp","a2a","http","grpc"],"default":"http"},"endpoint":{"type":"string"},"pricePerCall":{"type":"number","minimum":0,"default":0},"currency":{"type":"string","default":"USDC"},"network":{"type":"string","default":"base"},"pricingModel":{"type":"string","enum":["free","per-call"],"default":"free"},"price":{"type":"number","minimum":0},"pricing":{"$ref":"#/components/schemas/Pricing"}}},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}},"CategoryListResponse":{"type":"object","properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}},"Publisher":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"website":{"type":"string"},"verified":{"type":"boolean"},"stats":{"type":"object","properties":{"totalCalls":{"type":"integer"},"avgLatency":{"type":"number"},"uptime":{"type":"number"}}}}},"Pricing":{"type":"object","properties":{"model":{"type":"string","enum":["free","per-call","subscription","usage"]},"price":{"type":"number"},"currency":{"type":"string"},"limits":{"type":"object","properties":{"rateLimit":{"type":"integer"},"dailyLimit":{"type":"integer"}}}}},"AgentDirectory":{"type":"object","properties":{"meta":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"totalCapabilities":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"},"documentation":{"type":"string"},"openapi":{"type":"string"}}},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/Capability"}}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}},"AgentFactClaim":{"type":"object","properties":{"id":{"type":"string"},"subjectAgentId":{"type":"string"},"schemaVersion":{"type":"string"},"claimType":{"type":"string","enum":["owner_verification","compliance","performance","other"]},"issuedAt":{"type":"string","format":"date-time"},"issuerType":{"type":"string","enum":["did","wallet"]},"issuerDid":{"type":"string","nullable":true},"issuerWallet":{"type":"string","nullable":true},"issuerKeyType":{"type":"string","enum":["ed25519","eip191"]},"issuerPublicKey":{"type":"string","nullable":true},"payloadHash":{"type":"string"},"verified":{"type":"boolean"},"verifiedAt":{"type":"string","format":"date-time","nullable":true},"verificationError":{"type":"string","nullable":true},"provenance":{"type":"object","nullable":true},"createdAt":{"type":"string","format":"date-time"},"payload":{"type":"object","description":"Full claim payload (only when includeContent=true)"},"signature":{"type":"string","description":"Signature (only when includeContent=true)"}}},"AgentFactClaimListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentFactClaim"}},"pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total matching claims"},"limit":{"type":"integer"},"offset":{"type":"integer","nullable":true},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for next page"}}}}},"SignedAgentFactClaim":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["subject","issuer","claimType","claim","issuedAt"],"properties":{"schemaVersion":{"type":"string","default":"1.0"},"subject":{"type":"object","required":["agentId"],"properties":{"agentId":{"type":"string"}}},"issuer":{"type":"object","required":["type","keyType"],"properties":{"type":{"type":"string","enum":["did","wallet"]},"did":{"type":"string"},"wallet":{"type":"string"},"keyType":{"type":"string","enum":["ed25519","eip191"]},"publicKey":{"type":"string"}}},"claimType":{"type":"string","enum":["owner_verification","compliance","performance","other"]},"claim":{"type":"object","description":"Domain-specific claim content"},"evidence":{"type":"array","items":{"type":"object"}},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"previousClaimHash":{"type":"string"}}},"signature":{"type":"string","description":"Cryptographic signature over the payload"}}},"AgentFactClaimResponse":{"type":"object","properties":{"id":{"type":"string"},"payloadHash":{"type":"string"},"verified":{"type":"boolean"},"verificationError":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}},"tags":[{"name":"Discovery","description":"Search and browse skills"},{"name":"Invocation","description":"Invoke skills with x402 payment"},{"name":"Publisher","description":"Skill publishing, updates, and renewal"},{"name":"Agent Discovery","description":"Machine-readable endpoints for AI agents"},{"name":"Agent Facts","description":"Verified agent fact claims with cryptographic provenance"},{"name":"Categories","description":"Category management"},{"name":"Rating","description":"Reviews and voting"},{"name":"System","description":"Health checks and platform status"}]}