REST API

Overview

PinBuilds provides a REST API for external integrations. The API powers the WordPress plugin and can be used to build custom integrations for any platform.

PinBuilds also provides a remote MCP endpoint for AI agents and coding assistants. If you want to use PinBuilds from Codex, Claude Code, Cursor, VS Code/GitHub Copilot, Windsurf, Hermes Agent, Gemini CLI, ChatGPT Apps, or another MCP client, see the MCP & Agent Tools docs.

Authentication

All API requests require an API key in the Authorization header:

Authorization: Bearer pb_live_your_key_here

Creating API Keys

1. Go to Settings in PinBuilds.
2. Scroll to API Keys and click Create API Key.
3. Copy the key immediately — it's only shown once.

You can have up to 5 active API keys. Keys can be revoked at any time from Settings.

Endpoints

MCP Endpoint

POST /api/mcp

Remote MCP endpoint for AI agents. It exposes tools for usage checks, profile and board listing, generated pin lookup, article status checks, pin generation, and scheduling.

Authentication:

Authorization: Bearer pb_live_your_key_here

Generic MCP config:

{
  "mcpServers": {
    "pinbuilds": {
      "type": "http",
      "url": "https://pinbuilds.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${PINBUILDS_API_KEY}"
      }
    }
  }
}

Use GET /api/mcp to return basic server metadata and OPTIONS /api/mcp for client preflight. Tool calls use JSON-RPC 2.0 over HTTP.

See MCP & Agent Tools for setup instructions by client.

Generate Pins

POST /api/v1/generate

Generate AI pins from a URL. When scheduleConfig is provided, pins are automatically scheduled to Pinterest.

Request body:

{
  "url": "https://yourblog.com/article-title",
  "scheduleConfig": {
    "startDate": "2026-03-05",
    "timezone": "America/New_York"
  }
}

• url (required): The article URL to generate pins from.
• profileId (optional): Explicit profile ID to use when the URL cannot be matched by domain alone, especially Etsy listing URLs.
• scheduleConfig (optional): Include to auto-schedule. The server resolves the Pinterest account and boards from your profile settings.

The server resolves pin count, generation mode, styles, and overlay settings from the matched site profile's defaults. Website profiles can generate Image, Infographic, or Mix pins. Shopify and Etsy profiles are automatically coerced to Image pins because product listings usually need product-focused visuals rather than infographics.

For Etsy, pass the shop profile's profileId when generating from listing URLs. Etsy listing URLs live on the shared etsy.com domain, so profileId tells PinBuilds which verified shop profile owns the request.

Rate limit: 10 requests/minute.

Etsy listing example:

{
  "url": "https://www.etsy.com/listing/123456789/product-name",
  "profileId": "profile_abc123"
}

List Pins

GET /api/v1/pins?batchId=abc123

Retrieve generated pins by batch ID (returned from the generate endpoint).

Rate limit: 200 requests/minute.

Schedule Pins

POST /api/v1/schedule

Schedule pins to a Pinterest board.

Request body:

{
  "pinIds": ["pin1", "pin2"],
  "boardId": "board-id",
  "accountId": "account-id",
  "scheduleConfig": {
    "startDate": "2026-03-05",
    "timezone": "America/New_York"
  }
}

Rate limit: 100 requests/minute.

List Boards

GET /api/v1/boards

List all Pinterest boards from your connected accounts.

Rate limit: 200 requests/minute.

Check Usage

GET /api/v1/usage

Returns your current tier, usage, remaining monthly generations, pin count, and cycle reset date.

Rate limit: 200 requests/minute.

List Profiles

GET /api/v1/profiles

List all your site profiles with their settings. Each profile includes a profileType value:

Rate limit: 200 requests/minute.

Check Article Status

POST /api/v1/article-status

Check which article URLs have already been processed.

Request body:

{
  "urls": [
    "https://yourblog.com/post-1",
    "https://yourblog.com/post-2"
  ]
}

Returns which URLs have been generated and their batch IDs. Used by the WordPress plugin to determine which posts still need processing.

Rate limit: 200 requests/minute.

Error Handling

All endpoints return standard HTTP status codes:

Error responses include a JSON body with error and message fields.

Rate Limits

Rate limits are per API key. When rate limited, the response includes a Retry-After header.

MCP tool calls proxy to the REST endpoints, so the same rate limits and quota rules apply.