API overview

Lantfly has one API, served under /api/v3. The Console, the CLI and SDKs, integrations such as Zapier, Make and n8n, AI apps connected over MCP, and actors while they run all call the same API. Anything you can do in the Console, you can do with an API call.

This guide covers the rules every endpoint shares. For every path, parameter and schema, see the API reference.

Base URL

Base URL

https://lantfly.com/api/v3

All paths in these docs are relative to that base. For example, GET /me means GET https://lantfly.com/api/v3/me.

Two surfaces live outside the base path:

Surface	Address	Page
MCP server for AI apps	https://lantfly.com/mcp	MCP & AI agents
Sign-in (Console sessions)	https://lantfly.com/csl/auth/v1/login	Authentication

A first request

Who am I?

curl https://lantfly.com/api/v3/me \
  -H "Authorization: Bearer $LANTFLY_TOKEN"

Create the token under Settings → API & integrations in the Console. See Authentication.

Conventions

JSON

• Requests and responses are JSON (Content-Type: application/json), except where an endpoint says otherwise: dataset exports (CSV, XLSX, JSONL…), key-value records (stored with their own content type) and file downloads.

• Keys are snake_case: default_dataset_id, wait_for_finish, per_page.

• A single object comes back wrapped in data:

  Single object

  { "data": { "id": "6f1c…", "status": "SUCCEEDED" } }

• A list comes back as data plus meta. See Pagination.

  List

  { "data": [ { "id": "…" } ], "meta": { "current_page": 1, "last_page": 4, "per_page": 25, "total": 92 } }

• Every error has one shape, { "error": { "code", "message", "fields"?, "details"? } }. See Errors.

Timestamps

Timestamps are ISO 8601 in UTC with milliseconds, for example 2026-11-03T08:15:30.123Z. Send dates in the same format. Social listening endpoints that take a calendar day (from, to) use YYYY-MM-DD in the project's timezone.

Language

Error and validation messages follow the request's Accept-Language header. Lantfly supports en and vi. Without the header, messages use the language saved in your profile.

Messages in Vietnamese

curl https://lantfly.com/api/v3/actors/does-not-exist \
  -H "Authorization: Bearer $LANTFLY_TOKEN" \
  -H "Accept-Language: vi"

Branch on error.code, which is the same in every language. Don't parse message.

Acting for an organization

Requests act for your own account unless you send X-Lantfly-Account: <organization id> or use a token created for an organization. See Organizations.

Retrying writes safely

POST, PUT, PATCH and DELETE accept an optional Idempotency-Key header, so you can retry after a timeout without running the command twice. See Idempotency.

OpenAPI specification

The full specification is public and needs no token:

OpenAPI 3.1

https://lantfly.com/api/v3/openapi.yaml

Paste the URL into Postman (Import → Link), Swagger Editor, Insomnia or an SDK generator to get a ready collection or a typed client.

Removed versions

Earlier paths are gone. A request to /api/v1/…, /v2/… or /v3/… (without /api) answers 410 Gone, whatever the method and before any authentication:

410 api_version_removed

{
  "error": {
    "code": "api_version_removed",
    "message": "…",
    "details": { "current": "https://lantfly.com/api/v3" }
  }
}

Move the call to details.current. See Versioning.

In this section

Page	What it covers
Authentication	API tokens, scoped tokens, run tokens
Organizations	X-Lantfly-Account, organization tokens
Errors	Error shape and every code
Pagination	page, per_page, meta, storage paging
Idempotency	Idempotency-Key and replays
Rate limits	Request budgets, concurrent runs, 429
Signed links	Public storage links and rotating keys
Webhook signatures	Verifying X-Lantfly-Signature
Actor Standby	Calling an actor as an HTTP server
Versioning	How the API changes