Skip to content
Listener.comDevelopers

Library & research

Workspace library files, web research, podcast search and insertion-order parsing.

List library files

GET/v1/library/files
library:read

Files in the workspace library, newest upload first: filename, type, size, parse status, whether extracted text is available and a short preview.

SDKlistener.library.files.list()client.library.files.list()

Query parameters

  • limitinteger1 to 100
    Page size, 1–100 (default 25).

    Default 25

  • cursorstring
    Opaque cursor from the previous page's next_cursor.

Returns

200

OK

  • objectstringrequired
  • urlstringrequired
  • dataarray of objectsrequired
    Show child attributesHide child attributes
  • has_morebooleanrequired
  • next_cursorstringrequirednullable
    Pass as cursor to get the next page; null on the last page.
  • metaobjectrequired
    The result's non-list fields (window, coverage, freshness, totals, note …).
    Show child attributesHide child attributes

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Retrieve a library file

GET/v1/library/files/{file_id}
library:read

One library file: metadata, extracted text (up to 12,000 characters), the structured summary when one exists and a 1-hour signed download URL. include_text=false returns metadata and the link only.

SDKlistener.library.files.retrieve()client.library.files.retrieve()

Path parameters

  • file_idstringrequired
    Library file id (see GET /v1/library/files).

Query parameters

  • include_textboolean

    Default true

Returns

200

OK

  • idstringrequired
  • filenamestringrequired
  • computed_atstringrequired
  • cache_age_secondsnumberrequired
  • objectstringrequired
  • media_typestring

    Default "application/octet-stream"

  • size_bytesinteger

    Default 0

  • detected_kindstring

    Default "unknown"

  • is_text_likeboolean

    Default false

  • parse_statusstring

    Default "unknown"

  • parse_warningsarray of strings
  • statusstring

    Default "ready"

  • uploaded_atstringnullable
  • uploaded_by_uidstringnullable
  • has_extracted_textboolean

    Default false

  • extracted_text_charsinteger
    Length of the stored extracted text (before the 12,000-character cap).

    Default 0

  • has_structured_summaryboolean

    Default false

  • previewstringnullable
    First ~280 characters of the stored preview text.
  • extracted_textstringnullable
    Stored extracted text, capped at 12,000 characters.
  • extracted_text_truncatedboolean

    Default false

  • structured_summarystringnullable
  • storage_pathstringnullable
  • download_urlstringnullable
    Signed GET URL (1 h) when the Storage bucket is configured.
  • download_url_expires_atstringnullable
  • notestringnullable

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Web research

GET/v1/research/web
library:read

Search the public web and return titles, URLs and snippets plus a short summary of the top hits, for context outside Listener (a brand's news, a competitor's show). configured=false with a note when search is not set up on this server, never an error.

SDKlistener.research.web()client.research.web()

Query parameters

  • querystringrequired
    Search text.
  • max_resultsinteger1 to 10

    Default 5

Returns

200

OK

  • querystringrequired
  • configuredbooleanrequired
  • computed_atstringrequired
  • cache_age_secondsnumberrequired
  • objectstringrequired
  • summarystringnullable
  • sourcesarray of objects
    Show child attributesHide child attributes
  • total_resultsintegernullable
  • notestringnullable

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Search podcasts

GET/v1/podcasts/search
library:read

Search podcasts outside the workspace (prospects, competitors, a guest's own show) by name or keyword: title, publisher, artwork, categories, episode count, Apple / Spotify ids and RSS URL. configured=false with a note when the search provider is not configured.

SDKlistener.podcasts.search()client.podcasts.search()

Query parameters

  • querystringrequired
    Search text.
  • limitinteger1 to 20
    Maximum number of items to return.

    Default 10

Returns

200

OK

  • objectstringrequired
  • urlstringrequired
  • dataarray of objectsrequired
    Show child attributesHide child attributes
  • has_morebooleanrequired
  • next_cursorstringrequirednullable
    Pass as cursor to get the next page; null on the last page.
  • metaobjectrequired
    The result's non-list fields (window, coverage, freshness, totals, note …).
    Show child attributesHide child attributes

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Parse an insertion order

POST/v1/insertion-orders/parse
library:read

Read a PDF insertion order and return the extracted order, line items matched to workspace shows, rows that could not be matched, and ready-to-use proposed_create_campaign_args for POST /v1/campaigns. Writes nothing. Send exactly one source: library_file_id (from GET /v1/library/files), file_url (https, up to 4 MB) or file_base64 (upload_id refers to a file attached in Listener's agent chat). show_ids narrows show matching. Review unresolved_line_items before creating the campaign; never guess a show or impressions.

SDKlistener.insertionOrders.parse()client.insertion_orders.parse()

Headers

  • Idempotency-Keystringmax 255 chars
    Any unique string (≤ 255 chars). Replays within 24 h return the stored response with Idempotent-Replayed: true.

Request body

application/json
  • upload_idstringnullable
  • library_file_idstringnullable
  • file_urlstringnullable
  • file_base64stringnullable
  • file_namestringnullable
  • show_idsarray of stringsnullable
    Limit to these show ids (default: every show in the workspace).

Returns

200

OK

  • configuredbooleanrequired
    False when this server cannot reach the app's extractor (internal key / app URL missing); nothing was parsed.
  • computed_atstringrequired
  • cache_age_secondsnumberrequired
  • objectstringrequired
  • okboolean

    Default true

  • sourceobjectnullable
    Show child attributesHide child attributes
  • ioobjectnullable
    The extracted InsertionOrder (ioNumber, advertiser, flight, lineItems[], confidence, sourceQuotes …).
  • planobjectnullable
    The app's CampaignPlan as returned (camelCase); proposed_create_campaign_args is the same plan in POST /v1/campaigns's shape.
  • proposed_create_campaign_argsobjectnullable
    Exactly the argument names `POST /v1/campaigns` accepts, ready to pass through.
    Show child attributesHide child attributes
  • unresolved_line_itemsarray of objects
    Line items whose show could not be matched to a workspace show; ask the user, never guess.
    Show child attributesHide child attributes
  • warningsarray of strings
  • modelstringnullable
    The extraction model the app used.
  • notestringnullable

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found409confirmation_required413body_too_large429rate_limited500internal_error