API Reference

Base URL

https://api.signaldart.com/api/v1

Authentication

Two options, depending on what you are building:

• API key: create one in Team & API. Send it as Authorization: Bearer sk_.... Keys are scoped and revocable, and shown in full only once at creation.
• OAuth 2.0: for apps acting on behalf of other users. Register an application in the developer portal to get a client ID and secret, and request the scopes you need.

Core endpoints

Projects

• GET /projects: list projects (paginated, filterable by status)
• POST /projects: create a project from an idea
• GET /projects/{id}: fetch one project
• PATCH /projects/{id}: update
• DELETE /projects/{id}: soft delete

Research

• POST /projects/{id}/research: start the full pipeline
• GET /projects/{id}/research/latest: job status and stage
• POST /projects/{id}/competitor-discovery: competitors only
• POST /projects/{id}/seo-research: SEO engine only
• POST /projects/{id}/gap-analysis: gap engine only

Intelligence

• GET /projects/{id}/dashboard: everything the Overview renders in one call
• GET /projects/{id}/competitors · /features · /keywords · /market-gaps · /recommendations
• POST /projects/{id}/monitoring/start: enable continuous monitoring
• GET /projects/{id}/market-events · /alerts · /timeline

Reports

• POST /projects/{id}/reports: generate a report
• POST /reports/{id}/export: export to pdf, ppt, html, md or notion
• POST /reports/{id}/share: create a share link (optional password and expiry)

Assistant

• POST /assistant/chat: streaming answers over Server-Sent Events, with citations
• GET /assistant/conversations: conversation history

Public

• GET /health: liveness check (no auth)
• POST /waitlist: early-access signup (no auth)

Response shape

Every response wraps its payload in data. Lists add a meta object with page, page_size and total.

Pagination, filtering, sorting

Use ?limit= and ?offset= (or ?page=), plus ?search=, ?sort= and resource-specific filters such as ?status=.

Errors

• 400 bad request · 401 missing/invalid auth · 403 forbidden
• 404 not found · 422 validation failed · 429 rate limited
• 5xx server error, safe to retry with backoff

Rate limits

Limits depend on plan (60/hour on Free up to unlimited on Enterprise). Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. On 429, honour Retry-After.

Idempotency

Send an Idempotency-Key header on POST requests that create resources, so retries after a network failure do not duplicate work.

Webhooks

Rather than polling, subscribe to events in Developers → Webhooks. Available events: research.completed, research.failed, competitor.discovered, market.event, alert.created, report.ready and subscription.changed.

Each delivery is a JSON POST carrying three headers:

• X-SignalDart-Event: the event type
• X-SignalDart-Delivery: unique id; deduplicate on it, since retries can repeat an event
• X-SignalDart-Signature: t=<unix>,v1=<hmac>

Verify by computing HMAC-SHA256 over "<timestamp>.<raw body>" with your signing secret and comparing to v1 in constant time. Use the raw body: re-serializing the JSON changes the bytes and the signature will not match. Reject timestamps older than ~5 minutes to prevent replay.

Return 2xx within about 5 seconds; queue slow work. Failures retry with exponential backoff, then dead-letter for inspection and replay in the app. Endpoints must be HTTPS, and outbound requests are SSRF-protected.

SDKs

Official clients wrap auth, retries with backoff, pagination and SSE streaming: Python (signaldart), TypeScript (@signaldart/sdk) and Go (github.com/signaldart/signaldart-go). Java, C# and PHP clients are generated from the OpenAPI spec with openapi-generator.

They are not published to public registries yet. Install from the repository until they are.