Automated Media Lists

Medialyst can turn a campaign brief into a researched journalist list in two ways: hand the brief to a person with a browser deep link, or run the entire workflow from your system with the asynchronous REST API.

Both methods create the same organization-scoped media-list table used by the Medialyst app.

Choose A Method

Use the API as the primary method when the workflow should complete without a person. Use a deep link when you want Medialyst to prepare the workflow but keep a person in control of approval and credit spend.

Approval-Gated Browser Deep Link

Send a signed-in user to this URL with a URL-encoded campaign brief:

https://medialyst.ai/app/_/workflow/campaign?prompt=[URL-ENCODED-PROMPT]

The _ segment resolves to the user's current organization. Medialyst preserves the destination through sign-in or onboarding, automatically submits the prompt to the campaign agent, and presents the proposed plan for review. No credits are spent until the user approves the plan. Normal media-list credit usage begins after approval.

Build the link with a URL API instead of concatenating unescaped text:

const prompt =
    "Find Canadian journalists covering PR technology and AI media tools.";
const url = new URL("https://medialyst.ai/app/_/workflow/campaign");

url.searchParams.set("prompt", prompt);

console.log(url.toString());

The resulting link can be placed behind a Build in Medialyst button, returned by another agent, or added to a CRM record. Because query strings can appear in browser history and server logs, do not put credentials or other secrets in the prompt.

Fully Automated REST API

Use the asynchronous media-list API when an agent or backend service should create and retrieve the list without waiting for a person to approve it. The create request returns immediately with a job ID while discovery and enrichment run in the background.

The API bypasses the browser approval step and starts list creation as soon as the request is accepted. Normal media-list credits and plan limits apply.

After the background job creates the table, it appears on the Media Lists page for members of the API key's organization. If that page is already open, refresh it to load lists created outside the browser session.

Before You Start

Create an API key from the Medialyst Developers page with the media_lists:manage scope. Store the key in secret storage or an environment variable such as MEDIALYST_API_KEY.

All examples below use https://medialyst.ai/api as the API base URL.

1. Create A List Job

Send a campaign brief and target list size:

curl --request POST \
  'https://medialyst.ai/api/v1/media-lists:create-async' \
  --header "Authorization: Bearer $MEDIALYST_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: launch-brief-2026-07' \
  --data '{
    "prompt": "Find US journalists covering enterprise AI infrastructure and cloud spending for our product launch.",
    "target_list_size": 50
  }'

The response is accepted immediately:

{
  "job_id": "job_01HT...",
  "status": "pending",
  "target_list_size": 50,
  "status_url": "/api/v1/jobs/job_01HT..."
}

Use the returned target_list_size as the effective limit. It can be lower than the requested value when the organization's plan has a lower article limit.

Idempotency

Send a stable, unique Idempotency-Key for every logical creation request. Repeating the same key with the same normalized prompt and effective target returns the existing job. Reusing it with different input returns 409 Conflict.

For compatibility, existing integrations may continue sending topic instead of prompt and max_articles instead of target_list_size. New integrations should use the canonical fields shown above. If both size fields are supplied, their values must match.

2. Poll The Job

Poll the returned status URL until status is complete or failed:

curl \
  'https://medialyst.ai/api/v1/jobs/job_01HT...' \
  --header "Authorization: Bearer $MEDIALYST_API_KEY"

While enrichment is running, the response includes progress and row counts:

{
  "job_id": "job_01HT...",
  "status": "processing",
  "target_list_size": 50,
  "progress": {
    "stage": "enrichment",
    "percent": 72,
    "message": "Enriching journalist profiles"
  },
  "result": {
    "workflow_id": "tbl_01HS...",
    "total_rows": 50,
    "ready_rows": 36
  }
}

Status values are:

Poll every few seconds rather than in a tight loop. The API allows at most three concurrent pending or processing media-list jobs per API key.

3. Read Results

Add include=results to read normalized journalist rows from the job endpoint:

curl \
  'https://medialyst.ai/api/v1/jobs/job_01HT...?include=results&limit=50' \
  --header "Authorization: Bearer $MEDIALYST_API_KEY"

The response returns normalized journalists in the top-level rows array. Each row uses the stable journalist_list_v1 shape, including journalist identity and contact fields, outlet information, match score and reasoning, recent articles, and the source workflow ID. Use page.next_cursor as cursor on the next request until it is null. A page can contain at most 200 rows.

Results can be requested while the job is processing. Fields produced by Journalist Profile enrichment may remain null until the corresponding row is ready.

UI Visibility And Ownership

• The generated list is visible to members of the same organization as the API key.
• It counts toward that organization's active media-list allowance.
• It appears in the app after the worker creates the workflow table; the initial 202 Accepted response alone does not mean the table exists yet.
• A failure before table creation produces no list in the UI. A later pipeline failure can leave a partially populated list available for inspection.

Common Errors

For the generated request schema and operation metadata, see the interactive REST API reference or raw OpenAPI document.