toksta Analysis API

openapi: 3.2.0
info:
  title: Toksta Public Analysis 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: Analysis
paths:
  /v1/creators/content-match:
    post:
      operationId: startContentMatch
      summary: Start content match analysis
      tags:
      - Analysis
      description: 'Start LinkedIn content-fit analysis for a creator selection. Requires a user-scoped key.


        **Selection (provide exactly one):** `creator_ids`, `result_set_id`, or `result_set_ids`.


        **Topic criteria:** for ad hoc runs (no `campaign_id`) you MUST provide `topic_keywords` (array of strings). The field is `topic_keywords`, NOT `topics`. When `campaign_id` is supplied, criteria are read from the campaign instead.


        Returns `202` with **prefixed** job IDs in the form `content-fit:<uuid>` under `data.job_ids` and `data.jobs[].job_id`. `jobs_created` is 0 for creators already analyzed. Use those IDs with `POST /v1/content-match/results`. Cost: 3/5/8 credits per analysis based on `posts_to_analyze` (10/20/30).'
      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]).
                campaign_id:
                  type: string
                  description: Optional campaign UUID. When set, content criteria come from the campaign.
                campaign_brief:
                  type: string
                  description: Optional human-readable brief used as the analysis name.
                topic_keywords:
                  type: array
                  items:
                    type: string
                  description: 'Topic keywords for ad hoc content match. REQUIRED when no campaign_id is provided. (Alias: `keywords`.)'
                linkedin_content_types:
                  type: array
                  items:
                    type: string
                    enum:
                    - image
                    - video
                    - carousel
                  description: Optional content-type filter.
                posts_to_analyze:
                  type: integer
                  enum:
                  - 10
                  - 20
                  - 30
                  description: Posts analyzed per creator. 10 (3cr), 20 (5cr), or 30 (8cr). Defaults to 10.
              example:
                creator_ids:
                - f0e1d2c3-b4a5-4678-9abc-def012345678
                topic_keywords:
                - developer tools
                - API platforms
                - DevEx
                posts_to_analyze: 10
      security:
      - bearerAuth: []
      responses:
        '202':
          description: Content match jobs queued. Job IDs are prefixed `content-fit:<uuid>`.
          content:
            application/json:
              schema:
                type: object
                description: Content match jobs queued. Job IDs are prefixed `content-fit:<uuid>`.
                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
                    campaign_id: null
                    posts_to_analyze: 10
                    jobs_created: 2
                    job_ids:
                    - content-fit:56232ac2-8068-4dcb-9d1a-1f2e3a4b5c6d
                    - content-fit:7a8b9c0d-1e2f-4a3b-8c9d-0e1f2a3b4c5d
                    jobs:
                    - creator_id: f0e1d2c3-b4a5-4678-9abc-def012345678
                      analysis_id: 56232ac2-8068-4dcb-9d1a-1f2e3a4b5c6d
                      job_id: content-fit:56232ac2-8068-4dcb-9d1a-1f2e3a4b5c6d
                      status: pending
                      cached: false
                      message: Content analysis started. This may take a minute.
                      creator_name: Jane Marketer
                      profile_url: https://www.linkedin.com/in/jane-marketer/
                    failures: []
                  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/creators/audience-match:
    post:
      operationId: startAudienceMatch
      summary: Start audience match analysis
      tags:
      - Analysis
      description: 'Start LinkedIn audience-fit analysis for a creator selection. Requires a user-scoped key.


        **Selection (provide exactly one):** `creator_ids`, `result_set_id`, or `result_set_ids`.


        **Audience criteria:** for ad hoc runs (no `campaign_id`) provide at least one of `campaign_brief`, `target_audience`, `audience_keywords` (array), or `target_audience_criteria` (array). When `campaign_id` is set, criteria are read from the campaign.


        Returns `202` with **prefixed** job IDs in the form `audience-fit:<uuid>`. Use those IDs with `POST /v1/audience-match/results` or `/details`. Cost: 10/20/30 credits per analysis based on `analysis_depth`.'
      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]).
                campaign_id:
                  type: string
                  description: Optional campaign UUID. When set, audience criteria come from the campaign.
                campaign_brief:
                  type: string
                  description: Free-text brief describing the target audience (ad hoc).
                target_audience:
                  type: string
                  description: Alias for campaign_brief (ad hoc).
                audience_keywords:
                  type: array
                  items:
                    type: string
                  description: 'Audience keywords (ad hoc). Alias: `keywords`.'
                target_audience_criteria:
                  type: array
                  items:
                    type: string
                  description: Free-form audience criteria strings (e.g. job titles, seniorities, industries) for ad hoc runs.
                analysis_depth:
                  type: string
                  enum:
                  - quick_scan
                  - deep_dive
                  - comprehensive
                  description: Analysis depth. quick_scan (10cr), deep_dive (20cr), comprehensive (30cr). Defaults to quick_scan.
              example:
                creator_ids:
                - f0e1d2c3-b4a5-4678-9abc-def012345678
                target_audience_criteria:
                - VP Marketing
                - Head of Growth
                - B2B SaaS
                analysis_depth: quick_scan
      security:
      - bearerAuth: []
      responses:
        '202':
          description: Audience match jobs queued. Job IDs are prefixed `audience-fit:<uuid>`.
          content:
            application/json:
              schema:
                type: object
                description: Audience match jobs queued. Job IDs are prefixed `audience-fit:<uuid>`.
                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
                    selection:
                      source: creator_ids
                      selected_count: 1
                    campaign_id: null
                    analysis_depth: quick_scan
                    jobs_created: 1
                    job_ids:
                    - audience-fit:a5f1eeb5-ee98-41bc-8b2c-3d4e5f6a7b8c
                    jobs:
                    - creator_id: f0e1d2c3-b4a5-4678-9abc-def012345678
                      analysis_id: a5f1eeb5-ee98-41bc-8b2c-3d4e5f6a7b8c
                      job_id: audience-fit:a5f1eeb5-ee98-41bc-8b2c-3d4e5f6a7b8c
                      status: pending
                      cached: false
                      message: Audience analysis started. This may take a few minutes.
                      creator_name: Jane Marketer
                      profile_url: https://www.linkedin.com/in/jane-marketer/
                    failures: []
                  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/content-match/results:
    post:
      operationId: getContentMatchResults
      summary: Get content match results
      tags:
      - Analysis
      description: 'Fetch content-match analysis results.


        **Two selection modes:**

        1. By job: `job_id` (string) or `job_ids` (array). Accepts the prefixed form `content-fit:<uuid>` or the bare analysis UUID.

        2. By creators: `creator_ids`/`result_set_id`/`result_set_ids` (optionally with `campaign_id`) to fetch the latest saved analysis per creator.


        `detail_level: "full"` adds the `results` array. Use `wait_seconds` to poll inline.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              properties:
                job_id:
                  type: string
                  description: A single 

# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/toksta/refs/heads/main/openapi/toksta-analysis-api-openapi.yml