Custom API Integration

What this connection is for

Pull records from any REST endpoint and map them into the Product Graph.

How your data reaches Specky

Specky pulls from Custom API on a schedule. A sync runs when you open your workspace if the data is stale, and you can also start one by hand from the integration card.

Before you start

• API Endpoint (Required) — The full URL of the API endpoint that returns JSON data.
• API Key / Bearer Token (Required) — Sent as Authorization: Bearer <token> header.
• Data JSON Path (optional) (Optional) — Dot-notation path to the array of items in the response. Leave empty if the response is an array.
• Title Field (optional) (Optional) — Which field in each item to use as the node title. Defaults to 'title' or 'name'.
• Content Field (optional) (Optional) — Which field in each item to use as the main content. Defaults to 'description' or 'content'.

Setup

Open Settings → Integrations, find Custom API, and click Connect. The form will tell you what to paste and where to find it.

Requirements

Your API endpoint must:

1. Return JSON — either an array of objects or an object with a nested array
2. Support Bearer authentication — the API key is sent as Authorization: Bearer <token>
3. Be publicly accessible — Specky's server needs to reach it

How it works

1. Specky calls your endpoint with the provided API key
2. It extracts items from the response using your configured JSON path
3. Each item becomes a graph node with the title and content fields you specify
4. These nodes are available in the Product Graph for AI analysis and PRD generation

Example: Simple feedback API

// GET https://api.yourapp.com/v1/feedback
// Authorization: Bearer your-api-key
{
  "data": {
    "items": [
      { "title": "Need bulk export", "description": "Users want to export...", "source": "support" },
      { "title": "Mobile app slow", "description": "Performance issues on...", "source": "nps" }
    ]
  }
}

• Data JSON Path: data.items
• Title Field: title
• Content Field: description

Example: Array response

// GET https://api.yourapp.com/feedback
[
  { "name": "Feature request", "body": "We need..." },
  { "name": "Bug report", "body": "App crashes when..." }
]

• Data JSON Path: (leave empty)
• Title Field: name

After connecting

New Custom API items appear in Discovery alongside your other sources. You can search them, ask questions about them, and cite them in product work without opening another tab.

Disconnecting Custom API removes the connection and the signals it brought in.

Troubleshooting

• Connected, but nothing appears. Open the Custom API card and run a sync by hand. If it errors, the card shows the reason.
• "Upgrade to connect". Your plan caps how many integrations you can connect at once, and a few providers are Scale-only. Settings → Usage shows where you stand.
• Credentials stopped working. Tokens expire and get revoked. Reconnect with a fresh one — your existing signals are kept.

See the Custom API integration page for what it's for and the questions people usually ask first, or the Integrations Overview for how integrations work in general.