---
name: signalshelf-api-integration
description: Connect an application or agent to SignalShelf's existing public social-data APIs with server-side authentication, explicit sample/live mode, freshness controls, pagination and actionable errors.
---

# Integrate SignalShelf

Use this skill when a user wants to add SignalShelf calls to their application or connect an AI research workflow. Preserve the user's stack and existing secret-management conventions. Implement only the operations supported by their instance.

## Discover the interface

Obtain the user's deployment origin as `SIGNALSHELF_BASE_URL` and resolve `SIGNALSHELF_API_KEY` from a server environment or secret store. The production base is `https://signalshelf.dev`. Do not print the key, hardcode it in generated code, send it in a query string, or include it in frontend JavaScript.

Read `GET /api/v1/capabilities` and the relevant operations in `GET /api/openapi.json`. Use `GET /api/v1/coverage` to identify planned or experimental capabilities. A reference target in the coverage inventory is not necessarily implemented and is not a compatibility promise.

The current application includes:

- `POST /api/v1/profiles`: normalized public profiles for ten platforms. `mode` defaults to `demo`; set `mode: "live"` explicitly for real source data. Instagram accepts supported profile URLs; other handle forms are in the contract.
- `POST /api/v1/batch`: 1–10 profile lookup objects under `items`; inspect each result for partial failures.
- `POST /api/v1/posts`: Instagram public post/reel details from a URL or case-sensitive shortcode.
- GitHub, Bluesky and YouTube resource routes discovered from `/api/v1/capabilities`; use GET query parameters. These resources are live-only. Never invent a sample mode or unsupported options.
- `GET /api/v1/account/credits`, `/requests`, `/daily-usage`, `/top-endpoints`: authenticated private reporting, with no credit charge.

## Implement

Authenticate HTTP calls with the `x-api-key` header. Preserve the `{ data, meta }` envelope for lookup/resource routes. Lists may be under `data.items`; an individual resource payload may be under `data.data`. Account-reporting responses use their own documented shapes.

Treat `null` metrics as unavailable, not zero. Display `meta.fetched_at` when data age matters. Keep `sample: true` visibly labeled and separate from live results. Do not use sample responses to support production analytics or creator rankings.

Fresh successful lookups cost one credit. Samples, accepted cache hits and failures cost zero. `freshness` accepts `1h`, `24h` (default), `7d`, or `live`. Use an accepted freshness window unless a refresh is required; every forced refresh can incur another charge. Do not automatically retry fresh operations after ambiguous client timeouts without considering that the server may have finished.

Preserve opaque Bluesky cursors. Use GitHub's `pagination` fields and documented search caps; a list's estimated next page may be empty. Each page/options combination is a distinct cache identity and can require another fresh credit. Bound pagination to the user's requested result count and budget.

## Errors and verification

Handle HTTP status before reading the success payload:

- 400: invalid fields or unsupported options; correct the request.
- 401: missing/revoked credentials; do not retry blindly.
- 402: insufficient credits for fresh work.
- 404: unavailable public resource or unsupported route.
- 429: respect `Retry-After` and bound retries.
- 502/503: source extraction, access or upstream failure; report clearly.

For a new integration, verify a sample profile round trip where supported, then a specifically authorized public live request and a repeated cache hit. Check actual metadata and partial-batch errors. A successful public sample does not establish live source availability; a live check from one region does not establish global coverage. Keep sensitive auth headers out of logs and fixtures.

## Agent connections

When a SignalShelf MCP endpoint is available, connect to the deployment's `/mcp` with the user's configured key in an authorization header. Let the client manage MCP initialization and tool discovery. Read tool descriptions for costs and supported fields; never infer a tool from a planned reference target. Installation/configuration documentation lives at `/docs/mcp` and `/docs/agent-skills` on that deployment.