GUILDEST. 2025

Developer API

API DOCS

Integrate Guild agent identity, trust scores, and verification badges into your platform. Public endpoints require no authentication. Partner registration endpoints require an API key.

Base URLhttps://guild.nanocorp.app/api/v1

// Verified listing flow

VERIFIED LISTING FLOW

This is Guild's monetization path for builders: submit an agent, complete the Stripe checkout, and let the webhook promote the listing into the public registry with a verified badge.

/submit
  -> POST /api/submit-agent
  -> agent created with status="pending", verified=false
  -> GET /api/verified-listing/checkout?agent_id={id}&slug={slug}
  -> 303 redirect to Stripe payment link with client_reference_id
  -> POST /api/webhooks/nanocorp (checkout.session.completed)
  -> agents.status="active", agents.verified=true
  -> listing appears on /agents with the Verified badge

01 Submit the agent

A builder fills out /submit. Guild inserts the row through POST /api/submit-agent and returns the new agent id and slug.

02 Launch checkout

The Get Verified CTA routes through /api/verified-listing/checkout, which binds the agent identifier into Stripe using client_reference_id before redirecting to the hosted checkout page.

03 Webhook promotes the listing

After a successful payment, NanoCorp forwards checkout.session.completed to /api/webhooks/nanocorp. Guild resolves the agent from the checkout metadata and flips the row to status=active and verified=true.

04 Listing becomes public

The /agents directory and /agents/{slug} detail page both read the verified flag from the agents table and render the visible Verified badge for published listings.

// Agent Identity API

AGENT IDENTITY API

GET/api/v1/agents/{slug}/identity∅ No auth

Returns the full identity record for a registered agent. No authentication required. Use this to display agent profiles, trust scores, and verification status on your platform.

Example request

curl https://guild.nanocorp.app/api/v1/agents/financebot-pro/identity

Response — 200 OK

{
  "slug": "financebot-pro",
  "name": "FinanceBot Pro",
  "category": "finance",
  "capabilities": [
    "portfolio-analysis",
    "risk-assessment",
    "tax-optimization"
  ],
  "trust_score": 92,
  "verified": true,
  "status": "active",
  "external_badges": [
    {
      "platform": "agentgrid",
      "verified": true,
      "badge_url": "https://agentgrid.com/badges/financebot-pro",
      "profile_url": "https://agentgrid.com/agents/financebot-pro"
    }
  ],
  "guild_profile_url": "https://guild.nanocorp.app/agents/financebot-pro",
  "badge_url": "https://guild.nanocorp.app/api/v1/agents/financebot-pro/badge"
}

// Response fields

Field	Type	Description
`slug`	`string`	Unique identifier for the agent. Used in all API paths.
`trust_score`	`integer`	Trust score from 0 to 100.90+ = green (exceptional) · 80–89 = amber (strong) · below 80 = muted
`verified`	`boolean`	true when the agent holds a paid Verified listing. Verified agents receive priority placement in the Guild registry.
`capabilities`	`string[]`	Array of capability tags assigned by Guild during the review process.
`external_badges`	`object[]`	Partner platform badges. Each object includes platform, verified, badge_url, and profile_url.Currently populated for AgentGrid. More partners coming.
`status`	`enum`	Current listing status."active" \| "approved" \| "pending" \| "rejected"
`guild_profile_url`	`string`	Canonical Guild profile URL for this agent.
`badge_url`	`string`	URL of the embeddable SVG trust badge for this agent.

// Agent Registration API

AGENT REGISTRATION API

POST/api/v1/agents🔑 Auth required

Register an agent on Guild. Requires a partner API key passed as X-Guild-API-Key header or Authorization: Bearer <key>. Newly registered agents appear in the Guild registry after manual review.

Authentication: Pass your API key using either header format:
X-Guild-API-Key: guild_partner_xxxxxxxxxxxxxxxxAuthorization: Bearer guild_partner_xxxxxxxxxxxxxxxx

Request body

{
  "name": "My Agent",
  "slug": "my-agent",
  "description": "What this agent does.",
  "category": "finance | ops | marketing | data | research | other",
  "builder_name": "Acme Corp",
  "builder_url": "https://acmecorp.com"
}

// Request fields

Field	Type	Description
`name`	`string`	Display name of the agent. Required. Max 255 chars.
`slug`	`string`	URL-safe unique identifier. Optional — auto-generated from name if omitted.
`description`	`string`	What the agent does. Required.
`category`	`enum`	Agent category. Required."finance" \| "ops" \| "marketing" \| "data" \| "research" \| "other"
`builder_name`	`string`	Name of the builder or company. Required. Max 255 chars.
`builder_url`	`string`	Builder website URL. Optional.

curl example

curl -X POST https://guild.nanocorp.app/api/v1/agents \
  -H "Content-Type: application/json" \
  -H "X-Guild-API-Key: your_api_key_here" \
  -d '{
    "name": "My Agent",
    "slug": "my-agent",
    "description": "What this agent does.",
    "category": "finance",
    "builder_name": "Acme Corp",
    "builder_url": "https://acmecorp.com"
  }'

Responses

201Created

{
  "slug": "my-agent",
  "name": "My Agent",
  "category": "finance",
  "trust_score": 0,
  "verified": false,
  "status": "pending",
  "guild_profile_url": "https://guild.nanocorp.app/agents/my-agent",
  "badge_url": "https://guild.nanocorp.app/api/v1/agents/my-agent/badge"
}

401Unauthorized

{ "error": "Invalid or missing API key" }

409Conflict

{ "error": "An agent with that slug already exists. Please choose a different slug." }

422Unprocessable

{ "error": "Agent name is required (max 255 chars)." }

// Partner Badge Sync API

PARTNER BADGE SYNC API

POST/api/v1/agents/{slug}/badges🔑 Auth required

Upsert a partner verification badge onto an existing Guild agent profile. This endpoint is intended for integration partners like AgentGrid that need to mirror their verified state back onto Guild. The request must include your partner API key in the Authorization: Bearer <key> header or X-Guild-API-Key header, and the platform value must match the partner attached to that API key.

Authentication: Pass your API key using either header format:
Authorization: Bearer guild_partner_xxxxxxxxxxxxxxxxX-Guild-API-Key: guild_partner_xxxxxxxxxxxxxxxx

Request body

{
  "platform": "agentgrid",
  "verified": true,
  "badge_url": "https://agentgrid.com/badges/financebot-pro",
  "profile_url": "https://agentgrid.com/agents/financebot-pro"
}

// Request fields

Field	Type	Description
`platform`	`string`	Partner platform key. For AgentGrid, send "agentgrid".
`verified`	`boolean`	Partner verification state to display on Guild.
`badge_url`	`string`	Absolute URL to the partner-hosted badge asset.
`profile_url`	`string`	Absolute URL to the partner profile for this agent.

curl example

curl -X POST https://guild.nanocorp.app/api/v1/agents/financebot-pro/badges \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "platform": "agentgrid",
    "verified": true,
    "badge_url": "https://agentgrid.com/badges/financebot-pro",
    "profile_url": "https://agentgrid.com/agents/financebot-pro"
  }'

Responses

200OK

{
  "slug": "financebot-pro",
  "name": "FinanceBot Pro",
  "category": "finance",
  "capabilities": [
    "portfolio-analysis",
    "risk-assessment",
    "tax-optimization"
  ],
  "trust_score": 92,
  "verified": true,
  "status": "active",
  "external_badges": [
    {
      "platform": "agentgrid",
      "verified": true,
      "badge_url": "https://agentgrid.com/badges/financebot-pro",
      "profile_url": "https://agentgrid.com/agents/financebot-pro"
    }
  ],
  "guild_profile_url": "https://guild.nanocorp.app/agents/financebot-pro",
  "badge_url": "https://guild.nanocorp.app/api/v1/agents/financebot-pro/badge"
}

401Unauthorized

{ "error": "Invalid or missing API key" }

403Forbidden

{ "error": "API key is not authorized to write badges for platform \"agentgrid\"." }

404Not found

{ "error": "Agent not found" }

// Trust Badge Widget

TRUST BADGE WIDGET

GET/api/v1/agents/{slug}/badge∅ No auth

Embed a Guild trust badge on any web page using a standard <img>tag. The badge is served as SVG. It reflects the agent's current trust score and updates automatically. No authentication required.

Embed snippet

<img
  src="https://guild.nanocorp.app/api/v1/agents/{slug}/badge"
  alt="Guild Trust Badge"
  height="32"
/>

Badge preview

// SVG · 180×36px · transparent background available

NotesReturns image/svg+xml — works as a standard img src.
Includes CORS headers — safe to embed from any origin.
Badge automatically reflects live trust score — no cache-busting needed.
Replace {slug} with the agent's Guild slug.

Partner access

GET AN API KEY

API keys are issued to registered integration partners. The identity lookup and badge endpoints are open to the public — no key required. Keys are only needed to register agents and sync partner badges via the API.

// Request a partner key

Email guild@nanocorp.app to get a partner API key. We'll set you up with credentials and test the integration together.

Email guild@nanocorp.app →

What partners get

✓API key for programmatic agent registration

✓Access to POST /api/v1/agents

✓Access to POST /api/v1/agents/{slug}/badges

✓Sandbox test environment on request

✓Direct Slack/email support from the Guild team

✓Early access to new API endpoints