openapi: 3.2.0 info: title: Toksta Public Enrichment API description: Public API for Toksta creator data, analysis jobs, and SaaS workspace workflows. version: 0.1.0 servers: - url: https://api.toksta.com tags: - name: Enrichment paths: /v1/creators/enrich: post: operationId: startCreatorEnrichment summary: Start creator enrichment tags: - Enrichment description: 'Start LinkedIn profile enrichment for a creator selection. Requires a user-scoped key. **Selection (provide exactly one):** `creator_ids` (array of UUIDs), `result_set_id` (string), or `result_set_ids` (array). `creator_ids` takes precedence. This endpoint does NOT accept `creators: [{ profile_url }]`. **Synchronous completion:** if every requested creator is already enriched, the response is `200` with `jobs_created: 0` and `all_complete: true` — no job IDs are returned. Otherwise the response is `202`. Enrichment results are retrieved via `POST /v1/enrichments/results` using `creator_ids` (there is no per-job polling for enrichment). Costs 1 credit per profile enriched.' requestBody: required: true content: application/json: schema: type: object additionalProperties: true properties: creator_ids: type: array items: type: string description: UUID v4 string. description: Creator UUIDs to operate on. Takes precedence over result_set_id / result_set_ids when provided. result_set_id: type: string description: A single `result_set_id` returned by a prior discovery search. Resolved to its ranked creators. result_set_ids: type: array items: type: string description: Multiple result set IDs to merge (dedupe) into one creator selection. top_n: type: integer minimum: 1 description: When selecting from result set(s), take only the top N ranked creators. ranks: type: array items: type: integer minimum: 1 description: When a single result_set_id is provided, select specific 1-based ranks (e.g. [1,3,5]). example: creator_ids: - f0e1d2c3-b4a5-4678-9abc-def012345678 - a1b2c3d4-e5f6-4789-9abc-0123456789ab security: - bearerAuth: [] responses: '200': description: All requested creators were already enriched — no jobs created. Fetch results via POST /v1/enrichments/results with creator_ids. content: application/json: schema: type: object description: All requested creators were already enriched — no jobs created. Fetch results via POST /v1/enrichments/results with creator_ids. required: - success - data - meta properties: success: type: boolean enum: - true data: type: object additionalProperties: true description: Operation payload. See the example for the exact field structure. meta: type: object additionalProperties: true required: - request_id properties: request_id: type: string trace_id: type: string example: success: true data: creators_requested: 2 selection: source: creator_ids selected_count: 2 jobs_created: 0 all_complete: true already_enriched_count: 2 missing_linkedin_profiles: [] jobs: [] meta: request_id: req_01HXYZ... trace_id: 4f1d...c2 '202': description: Enrichment queued. Poll results with POST /v1/enrichments/results using the same creator_ids. content: application/json: schema: type: object description: Enrichment queued. Poll results with POST /v1/enrichments/results using the same creator_ids. required: - success - data - meta properties: success: type: boolean enum: - true data: type: object additionalProperties: true description: Operation payload. See the example for the exact field structure. meta: type: object additionalProperties: true required: - request_id properties: request_id: type: string trace_id: type: string example: success: true data: creators_requested: 2 selection: source: creator_ids selected_count: 2 jobs_created: 2 task_id: run_abc123 credits: required: 2 deducted: 2 remaining: 4998 already_enriched_count: 0 missing_linkedin_profiles: [] jobs: - job_id: enrichment:f0e1d2c3-b4a5-4678-9abc-def012345678 creator_id: f0e1d2c3-b4a5-4678-9abc-def012345678 creator_name: Jane Marketer profile_url: https://www.linkedin.com/in/jane-marketer/ status: queued meta: request_id: req_01HXYZ... trace_id: 4f1d...c2 '400': description: Bad request or validation error (`BAD_REQUEST` / `VALIDATION_ERROR`). content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Bad request or validation error (`BAD_REQUEST` / `VALIDATION_ERROR`). '401': description: Missing, invalid, or revoked API key. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Missing, invalid, or revoked API key. '402': description: Insufficient credits for this operation. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Insufficient credits for this operation. '403': description: API access disabled or workspace entitlement required. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: API access disabled or workspace entitlement required. '404': description: Resource not found, or result expired past retention. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Resource not found, or result expired past retention. '429': description: Rate limit exceeded — back off per `Retry-After`. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Rate limit exceeded — back off per `Retry-After`. '500': description: Unexpected server error. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Unexpected server error. '501': description: Endpoint is registered but not implemented yet. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Endpoint is registered but not implemented yet. /v1/enrichments/results: post: operationId: getEnrichmentResults summary: Get enrichment results tags: - Enrichment description: 'Fetch enrichment results for a creator selection. **Selection (provide one):** `creator_ids` (array of UUIDs), `result_set_id`, or `result_set_ids`. Because enrichment can complete synchronously (no job IDs), `creator_ids` is the reliable way to retrieve results. Set `detail_level: "full"` to include the `results` array with extended fields. Use `wait_seconds` to poll inline.' requestBody: required: true content: application/json: schema: type: object additionalProperties: true properties: creator_ids: type: array items: type: string description: UUID v4 string. description: Creator UUIDs to operate on. Takes precedence over result_set_id / result_set_ids when provided. result_set_id: type: string description: A single `result_set_id` returned by a prior discovery search. Resolved to its ranked creators. result_set_ids: type: array items: type: string description: Multiple result set IDs to merge (dedupe) into one creator selection. top_n: type: integer minimum: 1 description: When selecting from result set(s), take only the top N ranked creators. ranks: type: array items: type: integer minimum: 1 description: When a single result_set_id is provided, select specific 1-based ranks (e.g. [1,3,5]). detail_level: type: string enum: - summary - full description: Response verbosity. `summary` (default) returns trimmed fields; `full` returns the complete records. wait_seconds: type: integer minimum: 0 maximum: 30 description: Optional inline poll. Holds the request up to this many seconds (max 30) waiting for jobs to reach a terminal state before returning. Defaults to 0 (return immediately). example: creator_ids: - f0e1d2c3-b4a5-4678-9abc-def012345678 detail_level: summary wait_seconds: 10 security: - bearerAuth: [] responses: '200': description: Enrichment results. `results` (full records) is present only when detail_level=full. `meta` includes detail_level and wait_seconds. content: application/json: schema: type: object description: Enrichment results. `results` (full records) is present only when detail_level=full. `meta` includes detail_level and wait_seconds. required: - success - data - meta properties: success: type: boolean enum: - true data: type: object additionalProperties: true description: Operation payload. See the example for the exact field structure. meta: type: object additionalProperties: true required: - request_id properties: request_id: type: string trace_id: type: string example: success: true data: creators_requested: 1 completed: 1 pending: 0 selection: source: creator_ids selected_count: 1 results_summary: - creator_id: f0e1d2c3-b4a5-4678-9abc-def012345678 name: Jane Marketer profile_url: https://www.linkedin.com/in/jane-marketer/ followers_count: 48200 median_posts_per_month: 12 engagement_rate: 2.31 enriched_at: '2026-05-28T09:06:00Z' meta: request_id: req_01HXYZ... trace_id: 4f1d...c2 '400': description: Bad request or validation error (`BAD_REQUEST` / `VALIDATION_ERROR`). content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Bad request or validation error (`BAD_REQUEST` / `VALIDATION_ERROR`). '401': description: Missing, invalid, or revoked API key. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Missing, invalid, or revoked API key. '402': description: Insufficient credits for this operation. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Insufficient credits for this operation. '403': description: API access disabled or workspace entitlement required. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: API access disabled or workspace entitlement required. '404': description: Resource not found, or result expired past retention. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Resource not found, or result expired past retention. '429': description: Rate limit exceeded — back off per `Retry-After`. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Rate limit exceeded — back off per `Retry-After`. '500': description: Unexpected server error. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Unexpected server error. '501': description: Endpoint is registered but not implemented yet. content: application/json: schema: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true meta: type: object required: - request_id properties: request_id: type: string trace_id: type: string description: Endpoint is registered but not implemented yet. components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key