Custom API Integration

What it does

Import data from any REST API endpoint.

How your data reaches Specky

Specky pulls from Custom API on a schedule. A sync runs when you open your workspace if the data has gone stale, and you can trigger one by hand from the integration card at any time.

What you'll need

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

Go to Settings → Integrations, find Custom API, and click Connect.

Requirements

Your API endpoint must:

Return JSON — either an array of objects or an object with a nested array

Support Bearer authentication — the API key is sent as Authorization: Bearer <token>

Be publicly accessible — Specky's server needs to reach it

How it works

Specky calls your endpoint with the provided API key

It extracts items from the response using your configured JSON path

Each item becomes a graph node with the title and content fields you specify

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

Everything Specky pulls in from Custom API shows up in Discovery alongside your other sources, and feeds synthesis, clustering, and the AI chat's answers about your product. You don't have to do anything with it directly — it's there so the rest of Specky has something to reason over.

Disconnecting Custom API removes both 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.