Build with context. Keep control.

SPECTRA developer API

Read approved monitors, stored evidence, analytics and shared reports from your dedicated workspace.

International developer contract · 1.1.0-rc.3

This guide describes the production read-only contract. All examples are synthetic; use tenant-scoped list responses to obtain authorised identifiers.

Production API: https://api.spectra-ai.app/api/external/v1. SPECTRA-DDM credentials are bound to SPECTRA DDM Integration with the five approved read scopes.

Production base URL

https://api.spectra-ai.app/api/external/v1

The external DDM portal uses its backend to read SPECTRA-DDM. Humans manage the same organisation through tenant-scoped roles in SPECTRA. A human Organisation Administrator password is never an integration credential.

Authentication & quick start

1. Agree the required read scopes, approved recipient and secure delivery channel.
2. After approval, store the issued machine credential in your server secret store. Never embed it in a browser bundle, URL or logs.
3. Send Authorization: Bearer <machine credential> from your server. Start with GET /status.
4. Verify approved data, missing-scope rejection and foreign-record denial before portal release.

Use server-side credentials only. This static preview has no live request console.

Immutable tenant binding

The server derives the tenant from the credential on list, detail and download routes. Tenant override parameters or headers are rejected; they cannot select another organisation. Foreign and unavailable record identifiers return 404. Human sessions do not substitute for machine authentication.

Scopes & boundaries

status.read · monitors.read · content.read · analytics.read · reports.read. Only explicitly approved scopes are granted. Administration, credential management, monitor editing, writes, collection, publishing and paid analysis are inaccessible through this API.

Expiry & renewal

The agreed lifetime is five calendar months from issuance, preserving the UTC time and clamping the day if the target month is shorter. Record exact issuance and expiry in UTC and WAT (UTC+01:00) when access is issued. Begin renewal 30 days before expiry, escalate at 14 days and target cutover seven days before expiry. Renewal requires approval and secure delivery; reminders are not automatically scheduled. Credentials remain revocable earlier.

Data, freshness & visibility

These endpoints return stored records and on-demand aggregates of those records. Reading does not start continuous collection. Sample data, stored evidence and actively collected data must be labelled separately in your portal.

• Status and monitors: inspect collection state, last successful collection, last run, stale flags and source coverage. Provider availability is not a promise of ingestion.
• Content: active, non-archived, policy-approved normalized evidence. Provider redistribution rules can limit titles, references and derived fields. Full text and private provider payloads are unavailable. X references are not a full-text licence; YouTube visibility and freshness restrictions apply.
• Analytics: generatedAtUtc describes aggregation, not source collection freshness. Display sample size, evidence counts and truncation. Unavailable or withheld sentiment must not be rendered as neutral.
• Reports: only explicitly externally shared, unexpired reports. Results and downloads require completed, current, policy-valid evidence. Held, stale or failed reports may expose metadata with no results; download returns 409. Internal private reports are unavailable.

Geography describes the selected evidence role; it does not verify author residence, nationality or ethnicity. A language or place-name mention cannot establish identity. Unknown geography remains unknown.

Filters, pagination & errors

Use only parameters listed for each route. Unknown or repeated parameters are rejected. Lists default to page 1 and 25 items; maximum page size 100 and page number 100000. Carry the returned asOfUtc unchanged between pages; privacy removals and policy changes may still affect a page.

Date filters require an explicit time-zone offset: from is inclusive and to exclusive. For content and analytics date filters, the default window is seven days, maximum 31 days, with to ≤ asOfUtc. Search text is limited to 100 characters. Analytics are bounded (default 5000 evidence records; deployment configuration can differ); inspect truncation rather than treating samples as exhaustive. Rate limits are credential/configuration dependent (default 60 requests/minute); honor Retry-After.

Handled API errors use the Problem schema with safe code and requestId. Preserve request IDs for support; never send credentials in diagnostic logs. Tolerate new safe error codes within each status class. Unexpected server or proxy failures may have a different body; check status and content type before parsing.

Geography and language

Content and analytics accept comma-separated ISO2 countries with OR semantics: country=FR,JP. Each evidence item counts once; country rows can overlap. Omit country or use global alone for no geography restriction. unknown means no recorded location for the chosen role, excluding policy-withheld data. Roles are subject, origin, and source.

language=fr independently matches the exact stored language tag, case-insensitively. It does not match fr-CA, translate content, or infer location. Monitor reads return saved geographyTargets, languages, geographyBasis, and timeZone. Unavailable target references retain their IDs and available=false. Monitor edits remain human-application operations.

All assigned ISO countries are selectable. City coverage is partial; 13 territories have no map geometry. Provider-side country-wide search is not assumed. Deterministic English sentiment does not establish analysis coverage in other languages.

Runtime and report downloads

Examples require Bash and curl 7.76+; server JavaScript with fetch and AbortSignal.timeout (Node 20+); or Python 3.10+. For portable preview, extract the complete ZIP and open index.html, or run python3 -m http.server 8080 --bind 127.0.0.1 in the extracted directory. No install or external asset is needed.

Requests use a 15-second timeout. Honor Retry-After with bounded retries and jitter. JSON downloads contain the report envelope; CSV uses section,key,count rows, including summary, countries, sentiment, sources and selected trends. CSV is an aggregate projection, not full evidence or the entire JSON envelope.

Endpoint reference

Every request example runs on your server. Set SPECTRA_API_TOKEN through your secret manager. Replace synthetic identifiers with approved identifiers returned by your own tenant.

No matching endpoints. Try a route, scope or parameter name.

Response schemas