find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/influship-com:influship-com-shortlists-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Influship Shortlists API
  version: 1.0.0
  description: 'Public API for creator search, profile lookup, and campaign-fit analysis.


    ## Authentication


    Send your API key in the `X-API-Key` header on every authenticated request.


    ```bash

    curl -H "X-API-Key: your_api_key" https://api.influship.com/v1/creators/autocomplete?q=fitness

    ```


    ## Billing and Rate Limits


    The API uses credit-based billing and credit-based rate limits.


    - every endpoint has a credit cost

    - successful responses include `X-Credits-Charged` and `X-Credits-Features`

    - rate limits are enforced with per-minute and per-hour credit budgets

    - rate limit state is returned in the `RateLimit-*` headers


    Account-specific credit budgets take precedence over tier defaults. Use the returned

    `RateLimit-Limit-Minute` and `RateLimit-Limit-Hour` headers to read your effective budgets.


    ## Agentic Payments


    Use `https://api.influship.com/openapi.json` to discover endpoints that accept x402 v2 or MPP payments without an API key. It includes `402` payment challenges and `x-payment-info` metadata for the available payment methods.


    ## Pagination


    List endpoints use cursor pagination.


    - send `limit` to control page size

    - use `next_cursor` from the response to fetch the next page

    - stop when `has_more` is `false`


    Search has one special rule:


    - `POST /v1/search` creates a persisted search session

    - `GET /v1/search/{id}` paginates that session for free

    - free pagination is capped by the original search `limit`


    ## Errors


    Errors use a consistent shape:


    ```json

    {

    "error": {

    "code": "rate_limit_exceeded",

    "message": "Rate limit exceeded (per minute)"

    }

    }

    ```


    See each operation for exact request and response schemas.'
  contact:
    name: Influship Support
    email: support@influship.com
  license:
    name: Proprietary
    url: https://influship.com/terms
  x-guidance: 'Use the operation requestBody and query/path parameter schemas exactly as declared. Paid operations return HTTP 402 with x402 v2 and MPP payment challenges when called without payment; retry the same request with either x402 PAYMENT-SIGNATURE credentials (X-PAYMENT is also accepted for compatibility) or MPP Authorization: Payment credentials.'
servers:
- url: https://api.influship.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Shortlists
  description: Private creator shortlists saved to your API account or OAuth user.
paths:
  /v1/shortlists/{id}/delete:
    post:
      operationId: deleteShortlist
      summary: Delete your saved creator shortlist
      tags:
      - Shortlists
      description: Permanently remove a saved shortlist and its brief and notes. Requires its current version. Creator profiles are not deleted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                expected_version:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 2147483647
              required:
              - expected_version
              additionalProperties: false
      parameters:
      - schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        in: path
        name: id
        required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                        const: true
                      id:
                        type: string
                        format: uuid
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    required:
                    - deleted
                    - id
                    additionalProperties: false
                required:
                - data
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '402':
          description: Authenticated payment required response with a machine-readable billing classification and recovery action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error402'
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '422':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422'
        '429':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '503':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error503'
  /v1/shortlists:
    get:
      operationId: listShortlists
      summary: List your saved creator shortlists
      tags:
      - Shortlists
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        name:
                          type: string
                        brief:
                          type: string
                        profiles:
                          minItems: 1
                          maxItems: 8
                          type: array
                          items:
                            type: object
                            properties:
                              platform:
                                $ref: '#/components/schemas/Platform'
                              username:
                                type: string
                                minLength: 1
                                maxLength: 50
                            required:
                            - platform
                            - username
                            additionalProperties: false
                        notes:
                          type: string
                        version:
                          type: integer
                          exclusiveMinimum: 0
                          maximum: 2147483647
                        created_at:
                          type: string
                        updated_at:
                          type: string
                      required:
                      - id
                      - name
                      - brief
                      - profiles
                      - notes
                      - version
                      - created_at
                      - updated_at
                      additionalProperties: false
                required:
                - data
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '402':
          description: Authenticated payment required response with a machine-readable billing classification and recovery action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error402'
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '422':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422'
        '429':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '503':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error503'
    post:
      operationId: saveShortlist
      summary: Save or update your creator shortlist
      tags:
      - Shortlists
      description: Save up to eight Instagram profiles with a campaign brief and notes. Updating requires the current saved version. Reopen the selected profiles to retrieve their latest stored metrics and evidence.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                expected_version:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 2147483647
                name:
                  type: string
                  minLength: 1
                  maxLength: 80
                brief:
                  type: string
                  minLength: 1
                  maxLength: 500
                profiles:
                  minItems: 1
                  maxItems: 8
                  type: array
                  items:
                    type: object
                    properties:
                      platform:
                        $ref: '#/components/schemas/Platform'
                      username:
                        type: string
                        minLength: 1
                        maxLength: 50
                        pattern: ^[\p{L}\p{N}_.-]+$
                    required:
                    - platform
                    - username
                    additionalProperties: false
                notes:
                  default: ''
                  type: string
                  maxLength: 2000
              required:
              - name
              - brief
              - profiles
              additionalProperties: false
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      name:
                        type: string
                      brief:
                        type: string
                      profiles:
                        minItems: 1
                        maxItems: 8
                        type: array
                        items:
                          type: object
                          properties:
                            platform:
                              $ref: '#/components/schemas/Platform'
                            username:
                              type: string
                              minLength: 1
                              maxLength: 50
                          required:
                          - platform
                          - username
                          additionalProperties: false
                      notes:
                        type: string
                      version:
                        type: integer
                        exclusiveMinimum: 0
                        maximum: 2147483647
                      created_at:
                        type: string
                      updated_at:
                        type: string
                    required:
                    - id
                    - name
                    - brief
                    - profiles
                    - notes
                    - version
                    - created_at
                    - updated_at
                    additionalProperties: false
                required:
                - data
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '402':
          description: Authenticated payment required response with a machine-readable billing classification and recovery action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error402'
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '422':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422'
        '429':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '503':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error503'
  /v1/shortlists/{id}:
    get:
      operationId: getShortlist
      summary: Open your saved creator shortlist
      tags:
      - Shortlists
      parameters:
      - schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        in: path
        name: id
        required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      name:
                        type: string
                      brief:
                        type: string
                      profiles:
                        minItems: 1
                        maxItems: 8
                        type: array
                        items:
                          type: object
                          properties:
                            platform:
                              $ref: '#/components/schemas/Platform'
                            username:
                              type: string
                              minLength: 1
                              maxLength: 50
                          required:
                          - platform
                          - username
                          additionalProperties: false
                      notes:
                        type: string
                      version:
                        type: integer
                        exclusiveMinimum: 0
                        maximum: 2147483647
                      created_at:
                        type: string
                      updated_at:
                        type: string
                    required:
                    - id
                    - name
                    - brief
                    - profiles
                    - notes
                    - version
                    - created_at
                    - updated_at
                    additionalProperties: false
                required:
                - data
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '402':
          description: Authenticated payment required response with a machine-readable billing classification and recovery action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error402'
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '422':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422'
        '429':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '503':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error503'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              description: Machine-readable error code
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: Human-readable error message
              example: Request validation failed
            status_code:
              description: HTTP status code repeated for clients that consume the error body
              example: 402
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            param:
              description: Parameter that caused the error (if applicable)
              example: query
              type: string
            request_id:
              description: Optional request ID for debugging. Read the X-Request-Id response header when absent.
              example: 550e8400-e29b-41d4-a716-446655440000
              type: string
            details:
              description: Structured error context (e.g., field-level validation issues)
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
          required:
          - code
          - message
          additionalProperties: false
      required:
      - error
      additionalProperties: false
    Error400:
      description: Validation error response
      examples:
      - error:
          code: validation_error
          message: 'Invalid value for parameter ''limit'': must be between 1 and 100'
          param: limit
          request_id: 550e8400-e29b-41d4-a716-446655440000
      $ref: '#/components/schemas/Error'
    Error503:
      description: 'Service temporarily unavailable: a live data upstream, or a creator search, match or lookalike request that could not finish in time. Check Retry-After when present and retry with bounded backoff.'
      examples:
      - error:
          code: service_unavailable
          message: Live Instagram data is temporarily unavailable. Please retry shortly.
          request_id: 550e8400-e29b-41d4-a716-446655440000
          details:
            retry_after_seconds: 60
            upstream_error: upstream_rate_limited
      $ref: '#/components/schemas/Error'
    ErrorCode:
      type: string
      enum:
      - validation_error
      - invalid_parameter
      - missing_parameter
      - unauthorized
      - forbidden
      - payment_required
      - insufficient_credits
      - not_found
      - rate_limit_exceeded
      - quota_exceeded
      - internal_error
      - service_unavailable
      - upstream_contract_broken
      - database_error
      - seed_not_found
      - invalid_seeds
      - seed_resolution_failed
      - lookalike_failed
      - get_profiles_failed
      - post_analysis_failed
      - match_failed
      - scraping_failed
      - transcript_unavailable
      - transcript_not_available
      - transcription_limit_exceeded
      - transcription_unavailable
      description: Machine-readable error code for programmatic handling
      example: validation_error
    Platform:
      type: string
      enum:
      - instagram
      description: Social media platform
      example: instagram
    Error402:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              const: payment_required
            message:
              type: string
            status_code:
              type: number
              const: 402
            reason_code:
              type: string
              enum:
              - BILLING_SUSPENDED
              - PAYMENT_FAILED
              - PAYMENT_ACTION_REQUIRED
              - DISPUTE_OPENED
              - NO_PAYMENT_METHOD
              - SUBSCRIPTION_REQUIRED
              - NO_BUNDLE_CONFIGURED
              - BUNDLE_EXHAUSTED
            next_step:
              type: string
              enum:
              - update_payment_method
              - complete_authentication
              - contact_support
              - add_payment_method
              - reconnect_connection
              - upgrade_plan
            request_id:
              type: string
            details:
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
          required:
          - code
          - message
          - status_code
          - reason_code
          - next_step
          additionalProperties: false
      required:
      - error
      additionalProperties: false
      description: Payment required response. Returned when account billing or a subscription bundle requires attention.
      examples:
      - error:
          code: payment_required
          message: Payment authentication is required.
          status_code: 402
          reason_code: PAYMENT_ACTION_REQUIRED
          next_step: complete_authentication
          request_id: 550e8400-e29b-41d4-a716-446655440000
    Error500:
      description: Internal server error response
      examples:
      - error:
          code: internal_error
          message: An unexpected error occurred. Please try again later.
          request_id: 550e8400-e29b-41d4-a716-446655440000
      $ref: '#/components/schemas/Error'
    Error403:
      description: Permission error response
      examples:
      - error:
          code: forbidden
          message: Your plan does not include access to this endpoint
          request_id: 550e8400-e29b-41d4-a716-446655440000
      $ref: '#/components/schemas/Error'
    Error401:
      description: Authentication error response
      examples:
      - error:
          code: unauthorized
          message: API key missing or invalid
          request_id: 550e8400-e29b-41d4-a716-446655440000
      $ref: '#/components/schemas/Error'
    Error429:
      description: Rate limit exceeded response. Check Retry-After header for backoff timing. Also returned (without RateLimit-* headers) when an IP is temporarily blocked after repeated failed authentication attempts.
      examples:
      - error:
          code: rate_limit_exceeded
          message: Rate limit exceeded (per minute)
          request_id: 550e8400-e29b-41d4-a716-446655440000
      - error:
          code: rate_limit_exceeded
          message: Rate limit exceeded (per hour)
          request_id: 550e8400-e29b-41d4-a716-446655440001
      - error:
          code: rate_limit_exceeded
          message: Too many failed authentication attempts. Please try again later.
          request_id: 550e8400-e29b-41d4-a716-446655440002
      $ref: '#/components/schemas/Error'
    Error404:
      description: Not found error response
      examples:
      - error:
          code: not_found
          message: Creator with ID '123e4567-e89b-12d3-a456-426614174000' not found
          request_id: 550e8400-e29b-41d4-a716-446655440000
      $ref: '#/components/schemas/Error'
    Error422:
      description: Unprocessable entity response. The request was well-formed but a value failed a semantic rule (e.g. an invalid social handle format).
      examples:
      - error:
          code: validation_error
          message: Invalid Instagram username format
          param: username
          request_id: 550e8400-e29b-41d4-a716-446655440000
      $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key