---
title: "Create Source"
method: POST
path: "/api/v1/sources/{source_id}"
tags: ["Sources"]
---

# Create Source

`POST /api/v1/sources/{source_id}`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/sources/{source_id}`
- Auth: HTTP bearer

Create a new source. Behavior is source-specific: typically the source imports matching records immediately (when `pull_existing` or equivalent is set) and — for an ongoing source — keeps re-importing on a schedule.

Per-source body shapes and field semantics live in `/docs/source-detail/{source_id}.txt`. The route schema only enforces that the body is a JSON object; per-source validation runs inside the handler and surfaces as 400 with a specific message and, when multiple fields fail, an `errors[]` array of `{field, message}` entries.

Returns `source_instance_id` (the new source's UUID). The initial import runs asynchronously: the call returns as soon as the source is created and the import is queued, not when records have finished arriving.

## Path parameters

- `source_id` string, required

## Request body

- SourceCreateBody: Per-source create body. Shape depends on `source_id` — see the provider README under `modules/sources/` (and optionally `/docs/source-detail/{source_id}.txt`). Validated at the handler level; the schema only enforces that the body is a JSON object.

## Response `201`

Default Response

- object
  - `status` integer
  - `data` SourceCreateResponse: Create result envelope. `source_instance_id` is the new source's UUID — pass it to Sync / Get Source Data / Pause-Resume.
    - `source_instance_id` string, required: UUID of the newly created source instance.
    - `name` string, required: Display name echoed from the request (trimmed).
    - `created_at` string, date-time, required: UTC timestamp (ISO 8601) of source creation.
    - `pixel_id` string: Website-visitor sources only: tracking pixel id. Embed `pixel_script` on the monitored domain so visits can be recorded.
    - `pixel_script` string: Website-visitor sources only: HTML snippet to embed on the monitored domain.
    - `warning` string: Non-fatal warning when the source was created but a secondary setup step failed (e.g. Google Sheets real-time sync could not be enabled).

## Other responses

- `400`: Per-source validation failed (missing or invalid payload fields).
- `401`: Unauthorized — missing or invalid API key
- `402`: Credit consumption failed — the source row was archived and the initial pull did not start. Surface the message to the user; they likely need to top up.
- `403`: Forbidden. `code` says which permission refused: ROLE_FORBIDDEN (your role), INSUFFICIENT_SCOPE (the API key's scopes), WORKFLOW_FORBIDDEN (no access to the workflow), KEY_WORKFLOW_FORBIDDEN (the API key's workflow restriction).
- `404`: Unknown `source_id` — see the param description for supported slugs.
- `424`: The user is not connected to the integration this source depends on.
- `429`: Too Many Requests — rate limit exceeded. Check `Retry-After` header for seconds until the limit resets.

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)