API Documentation

Overview

The Flintt API lets you interact with your workspace programmatically. You can add companies and prospects to watch, create and manage signals, retrieve run results, and subscribe to real-time events via webhooks.

All API endpoints are prefixed with /v1/. Requests and responses use JSON. The management endpoints for API keys and webhooks use JWT authentication (your normal session token) and are prefixed with /api/.

http

GET  https://api.flintt.co/v1/signals
POST https://api.flintt.co/v1/companies

# Management (JWT auth)
GET  https://api.flintt.co/api/api-keys
POST https://api.flintt.co/api/outbound-webhooks

Authentication

All /v1/ endpoints are authenticated with an API key passed in the X-API-Key header. Keys are generated from your Flintt workspace settings and have the format flt_....

ℹ

API keys are shown once at creation and cannot be retrieved again. Store them securely. Treat them like passwords.

http

GET /v1/signals HTTP/1.1
Host: api.flintt.co
X-API-Key: flt_ab12ef34cd56...
Accept: application/json

If the key is missing or invalid, the API returns 401 Unauthorized.

API Keys

API keys are managed through the /api/api-keys endpoints. These require your standard JWT (Bearer token), not an API key.

GET/api/api-keys

Returns all API keys for the authenticated user. Key hashes are never returned; only the display prefix.

json

[
  {
    "id": "01234567-89ab-...",
    "name": "Production",
    "key_prefix": "flt_ab12ef34",
    "last_used_at": "2026-03-20T14:32:00Z",
    "revoked_at": null,
    "created_at": "2026-03-01T09:00:00Z"
  }
]

POST/api/api-keys

Create a new API key. Returns raw_key once. This value is never stored and cannot be retrieved again.

Body

Name	Type	Required	Description
`name`	`string`	required	A human-readable label for this key (e.g. "Production", "Zapier").

json

// Request
{ "name": "Production" }

// Response 201
{
  "id": "01234567-89ab-...",
  "name": "Production",
  "key_prefix": "flt_ab12ef34",
  "raw_key": "flt_ab12ef34cd5678901234567890abcdef1234...",
  "created_at": "2026-03-22T10:00:00Z"
}

DELETE/api/api-keys/{key_id}

Revoke an API key immediately. Any in-flight requests using the key will be rejected.

json

{ "ok": true }

Webhooks

Configure HTTP endpoints to receive real-time event notifications from Flintt. All webhook management endpoints require JWT authentication.

GET/api/outbound-webhooks

List all configured webhook endpoints. Signing secrets are never returned in list/get responses.

json

[
  {
    "id": "wh_01234...",
    "name": "My Server",
    "endpoint_url": "https://yourapp.com/flintt-webhook",
    "event_types": ["signal.run.completed", "prospect.created"],
    "active": true,
    "created_at": "2026-03-01T09:00:00Z",
    "updated_at": "2026-03-01T09:00:00Z"
  }
]

POST/api/outbound-webhooks

Create a webhook endpoint. Returns signing_secret once. Save it to verify incoming request signatures.

Body

Name	Type	Required	Description
`name`	`string`	required	Human-readable label.
`endpoint_url`	`string`	required	The HTTPS URL Flintt will POST events to.
`event_types`	`string[]`	required	Array of event types to subscribe to. See "Event types" below.
`active`	`boolean`	optional	Whether to immediately start delivering events. Defaults to true.

json

// Request
{
  "name": "My Server",
  "endpoint_url": "https://yourapp.com/flintt-webhook",
  "event_types": ["signal.run.completed", "prospect.created"]
}

// Response 201
{
  "id": "wh_01234...",
  "name": "My Server",
  "endpoint_url": "https://yourapp.com/flintt-webhook",
  "event_types": ["signal.run.completed", "prospect.created"],
  "signing_secret": "whsec_a1b2c3d4...",
  "active": true,
  "created_at": "2026-03-22T10:00:00Z"
}

PATCH/api/outbound-webhooks/{endpoint_id}

Update a webhook endpoint. All fields are optional; only provided fields are updated.

Body

Name	Type	Required	Description
`name`	`string`	optional	New label.
`endpoint_url`	`string`	optional	New destination URL.
`event_types`	`string[]`	optional	Replace the full list of subscribed event types.
`active`	`boolean`	optional	Pause (false) or resume (true) delivery.

DELETE/api/outbound-webhooks/{endpoint_id}

Delete a webhook endpoint permanently.

json

{ "ok": true }

POST/api/outbound-webhooks/{endpoint_id}/rotate-secret

Generate a new signing secret. The old secret becomes invalid immediately. Update your verification code before rotating.

json

{ "signing_secret": "whsec_newvalue..." }

Event types

Event	Fired when
`signal.run.completed`	A signal run finishes (success or partial).
`signal.run.result`	Each validated (relevant) result in a run.
`company.created`	A company is added to your workspace.
`prospect.created`	A pipeline deal is created.

Payload envelope

Every POST from Flintt wraps the event data in a consistent envelope:

json

{
  "event": "signal.run.completed",
  "delivery_id": "550e8400-e29b-...",
  "timestamp": "2026-03-22T10:00:00Z",
  "data": {
    "signal_id": "...",
    "run_id": "...",
    "status": "completed",
    "valid_count": 5,
    "raw_count": 12,
    "deal_count": 2
  }
}

Verifying signatures

Each request includes an X-Flintt-Signature: sha256=… header. Compute HMAC-SHA256(raw_body, signing_secret) and compare with the header value.

python

import hmac, hashlib

def verify_flintt_signature(body: bytes, secret: str, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

typescript

import { createHmac, timingSafeEqual } from "crypto";

function verifyFlinttSignature(
  body: string,
  secret: string,
  header: string
): boolean {
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(body).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Companies

Manage the companies you're watching. All endpoints require X-API-Key authentication.

GET/v1/companies

List all companies in your workspace, ordered by most recently updated.

Query params

Name	Type	Required	Description
`name`	`string`	optional	Filter by company name (case-insensitive partial match).

json

[
  {
    "id": "c1d2e3f4-...",
    "user_id": "u1a2b3c4-...",
    "name": "Acme Corp",
    "sector": "SaaS",
    "size": "51-200",
    "website": "https://acme.com",
    "estimated_revenue": null,
    "logo_url": "https://...",
    "enrichment_data": {},
    "created_at": "2026-03-01T09:00:00Z",
    "updated_at": "2026-03-20T14:00:00Z"
  }
]

POST/v1/companies

Add a company to your workspace. Fires a company.created webhook event.

Body

Name	Type	Required	Description
`name`	`string`	required	Company name.
`sector`	`string`	optional	Industry sector.
`size`	`string`	optional	Headcount range, e.g. "51-200".
`website`	`string`	optional	Company website URL.
`estimated_revenue`	`string`	optional	Revenue estimate.
`logo_url`	`string`	optional	URL of the company logo.

Prospects

Prospects represent pipeline deals: a company at a given stage in your sales funnel.

GET/v1/prospects

List pipeline deals, optionally filtered by stage.

Query params

Name	Type	Required	Description
`stage`	`string`	optional	Filter by stage key, e.g. "prospect", "qualified", "negotiating".
`limit`	`integer`	optional	Max results to return (1–100). Defaults to 50.

json

[
  {
    "id": "d1e2f3a4-...",
    "user_id": "u1a2b3c4-...",
    "company_id": "c1d2e3f4-...",
    "stage": "qualified",
    "next_step": "Send proposal",
    "estimated_value": 12000,
    "lead_score": 82,
    "visibility": "active",
    "days_in_stage": 5,
    "created_at": "2026-03-10T08:00:00Z",
    "updated_at": "2026-03-15T10:00:00Z"
  }
]

POST/v1/prospects

Create a pipeline deal for an existing company. Fires a prospect.created webhook event.

Body

Name	Type	Required	Description
`company_id`	`uuid`	required	ID of an existing company in your workspace.
`stage`	`string`	optional	Pipeline stage key. Defaults to "prospect".
`next_step`	`string`	optional	Short note on the next action.
`estimated_value`	`number`	optional	Deal value in your account currency.

Signals

Signals are automated intelligence triggers. They periodically scrape and validate buying signals for your target companies. Each signal has one or more tools and runs on a schedule.

GET/v1/signals

List all signals in your workspace.

json

[
  {
    "id": "s1a2b3c4-...",
    "name": "Series A funding rounds",
    "description": "French B2B SaaS companies raising Series A",
    "frequency": "weekly",
    "status": "active",
    "tool_count": 2,
    "last_run_at": "2026-03-20T06:00:00Z",
    "created_at": "2026-03-01T09:00:00Z"
  }
]

POST/v1/signals

Create a new signal. A signal must be built (via the app) before it can run.

Body

Name	Type	Required	Description
`name`	`string`	required	Signal name (max 160 chars).
`description`	`string`	optional	What the signal looks for.
`frequency`	`string`	required	"daily" \| "weekly" \| "monthly"

GET/v1/signals/{signal_id}

Retrieve a single signal by ID.

PATCH/v1/signals/{signal_id}

Update a signal's name, description, frequency or status.

Body

Name	Type	Required	Description
`name`	`string`	optional	New signal name.
`description`	`string`	optional	New description.
`frequency`	`string`	optional	"daily" \| "weekly" \| "monthly"
`status`	`string`	optional	"active" \| "paused"

DELETE/v1/signals/{signal_id}

Permanently delete a signal and all its associated runs and results.

⚠

This action is irreversible. All run history for this signal will be deleted.

json

{ "ok": true }

Runs

A run represents one execution of a signal. Each run collects raw results, validates them with AI, and optionally enriches matching companies.

GET/v1/signals/{signal_id}/runs

List all runs for a signal, newest first.

Query params

Name	Type	Required	Description
`from_date`	`string`	optional	ISO 8601 lower bound for run date.
`to_date`	`string`	optional	ISO 8601 upper bound for run date.

json

[
  {
    "id": "r1a2b3c4-...",
    "signal_id": "s1a2b3c4-...",
    "status": "completed",
    "run_mode": "scheduled",
    "started_at": "2026-03-20T06:00:00Z",
    "ended_at": "2026-03-20T06:04:32Z"
  }
]

GET/v1/signals/{signal_id}/runs/{run_id}

Retrieve the full detail of a run including raw results and validated results.

json

{
  "run": {
    "id": "r1a2b3c4-...",
    "signal_id": "s1a2b3c4-...",
    "status": "completed",
    "run_mode": "scheduled",
    "started_at": "2026-03-20T06:00:00Z",
    "ended_at": "2026-03-20T06:04:32Z"
  },
  "raw_results": [
    {
      "id": "rr_...",
      "company_name": "Acme Corp",
      "signal": "Acme Corp raised a €4M Series A round",
      "source_url": "https://techcrunch.com/...",
      "source_type": "news",
      "created_at": "2026-03-20T06:02:10Z"
    }
  ],
  "validation_results": [
    {
      "id": "vr_...",
      "is_valid": true,
      "confidence": 0.94,
      "company_name": "Acme Corp",
      "signal_summary": "Acme Corp closed a €4M Series A, hiring aggressively.",
      "why_now": "Fresh capital signals expansion budget.",
      "evidence_sources": [
        { "url": "https://techcrunch.com/...", "title": "Acme raises €4M" }
      ]
    }
  ]
}

Need help?

Reach out at support@flintt.io or open an issue on our GitHub.