---
title: "Create a tracked source"
method: POST
path: "/org/tracked-sources"
tags: ["Tracked Sources"]
---

# Create a tracked source

`POST /org/tracked-sources`

## Request

- Base URL: `https://apiv2.senso.ai/api/v1`
- URL: `https://apiv2.senso.ai/api/v1/org/tracked-sources`
- Auth: API key in header `X-API-Key`

Adds a citation-classification rule. `pattern` is normalized to a canonical form before storage (a `domain` to its eTLD+1, a `host` to its hostname), and `category` is only retained for the `tracked` tier. New rules are always `active` with `source_origin: manual`.

## Request body

- TrackedSourceRequest: Create/update payload for a citation-classification rule.
  - `pattern` string, required: The URL, host, or domain to match. Normalized to a canonical form on save (a `domain` to its eTLD+1); `path_prefix` and `exact_url` require a path.
  - `match_type` 'domain' | 'host' | 'path_prefix' | 'exact_url', required: The scope the pattern matches against.
  - `tier` 'primary' | 'tracked' | 'secondary', required: A cited URL's classification tier — `primary` (Owned: one of your own websites), `tracked` (Tracked: one of your configured tracked sources), or `secondary` (External: any other domain). The tiers partition citations, so every cited URL falls in exactly one of them.
  - `category` 'affiliated_domain' | 'published_content' | 'social' | 'press': Optional reporting label. Only retained for the `tracked` tier; ignored otherwise.
  - `label` string: Optional human-readable label for the rule.
  - `priority` integer: Optional tie-break priority when multiple rules match a URL.
  - `active` boolean: Whether the rule is applied. Ignored on create (new rules are always active); on update it is the only field honored for published rules.

## Response `201`

The created tracked source.

- TrackedSourceResponse: A per-org citation-classification rule.
  - `id` string, uuid, required: Unique identifier of the rule.
  - `org_id` string, uuid, required: The organization that owns this rule.
  - `pattern` string, required: The pattern the rule matches on. Patterns written through the API are normalized; rules seeded during onboarding or from published content may carry the raw URL (the classifier normalizes at match time).
  - `match_type` 'domain' | 'host' | 'path_prefix' | 'exact_url', required: The scope the pattern matches against.
  - `tier` 'primary' | 'tracked' | 'secondary', required: A cited URL's classification tier — `primary` (Owned: one of your own websites), `tracked` (Tracked: one of your configured tracked sources), or `secondary` (External: any other domain). The tiers partition citations, so every cited URL falls in exactly one of them.
  - `category` 'affiliated_domain' | 'published_content' | 'social' | 'press': Reporting label, present only for `tracked`-tier rules that carry one.
  - `label` string: Human-readable label, when set.
  - `priority` integer, required: Tie-break priority when multiple rules match a URL.
  - `source_origin` 'manual' | 'onboarding' | 'published', required: How the rule was created — `manual` (via the API/editor), `onboarding` (seeded from the org's website), or `published` (auto-created when content was published; read-only except for the `active` toggle).
  - `active` boolean, required: Whether the rule is currently applied.
  - `created_at` string, date-time, required: When the rule was created.
  - `updated_at` string, date-time, required: When the rule was last updated.

## Other responses

- `400`: The request body was invalid — either it failed field validation (`ValidationErrorResponse`) or was otherwise malformed (`ErrorResponse`).
- `401`: Missing or invalid credentials — supply a valid org API key in the `X-API-Key` header.
- `404`: The requested resource does not exist or is not visible to this key.
- `409`: The request conflicts with the current state (e.g. a duplicate).

---

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