Developers

PR Agents on Medialyst

Medialyst gives your agent the data: real-time news search and journalist enrichment, over REST and the MCP server. That's the layer underneath the work — every result grounded in live coverage and real, recent bylines, not model memory.

There are two ways to build on it.

Use newsjack.sh (the full agent)

newsjack.sh is the open-source PR agent built on Medialyst. It's the smoothest way to put Medialyst to work from Claude, ChatGPT, Cursor, or your own terminal — opinionated skills for the whole PR loop, not just raw tool calls.

  • Open source: github.com/elvisun/newsjack
  • OAuth device login: run newsjack login, approve the browser prompt, and you're connected — no API key to copy out of the terminal.
  • The full loop: find angles from live news, build a fit-scored journalist list, and draft pitches — with review and sending kept human-in-the-loop.

Reach for newsjack.sh when you want a working PR agent out of the box instead of assembling the primitives yourself.

Build your own agent (the primitives)

Prefer to wire Medialyst into your own agent? Point any MCP-capable client at the server and call the REST-backed tools:

https://medialyst.ai/api/mcp
  • get_credit_balance → GET /api/v1/credits/balance
  • create_media_list → POST /api/v1/media-lists:create-async
  • list_media_lists → GET /api/v1/media-lists
  • get_media_list_job → GET /api/v1/jobs/:jobId
  • get_media_list → GET /api/v1/media-lists/:mediaListId
  • delete_media_list → POST /api/v1/media-lists/delete
  • lookup_article → GET /api/v1/articles/lookup
  • lookup_articles → POST /api/v1/articles/lookup:batch
  • lookup_publication → GET /api/v1/publications/lookup
  • lookup_publications → POST /api/v1/publications/lookup:batch
  • lookup_journalist → POST /api/v1/journalists/lookup
  • search_news → POST /api/v1/news/search
  • query_pr_calendar → POST /api/v1/pr-calendar/query
  • list_journalist_moves → GET /api/v1/journalist-moves
  • enrich_journalists → POST /api/v1/journalists/enrich
  • get_journalist_enrichment_job → GET /api/v1/journalist-enrichment-jobs/:jobId

list_journalist_requests is MCP-only.

A few rules keep agents honest:

  • For one named journalist's email, call lookup_journalist. For article authors or many journalists at once, call enrich_journalists with journalist_reference sources: name requires at least one of publication, domain, or a real identifying url.
  • Use article_url for a real article from search_news or the user when enriching its author. Never invent URLs.
  • Use query_pr_calendar for planning moments, awareness days, conferences, and pitch timing.
  • Use lookup_article for one known article URL and optional Markdown; use lookup_articles for 1-10 URLs without Markdown.
  • Use lookup_publication for one outlet or article URL. lookup_publications accepts 1-25 cached/default URLs, or at most five with force_refresh: true.
  • Budget 0.1 credit per successful article URL and 0.01 credit per successful publication URL. Per-URL failures cost 0 credits.
  • All four lookup tools require media_lists:manage.
  • lookup_journalist takes q (name plus outlet) or a journalist_id and returns status: found (the deliverable email), checking (call again with the same input after retry_after_seconds), not_found (never guess an address), or ambiguous (call again with a candidate's journalist_id, or with the same q and find_live: true when none is the person). It needs no special scope.
  • A found email costs 1 credit; the same person is free for 30 days. A free plan gets 3 lookups a day, shared with enrich_journalists. On FREE_PLAN_DAILY_LIMIT, INSUFFICIENT_CREDITS, or LOOKUP_DAILY_CAP, relay the message and stop.
  • The signed-in app's credit-free Journalist Lookup and daily fair-use limit do not apply to this MCP tool; keep the API billing rules above.
  • Use fit_context.pitch on enrich_journalists when you want scored fit or pitch angles.
  • enrich_journalists is async-only: it returns a job id; poll get_journalist_enrichment_job until the job is complete or failed.
  • Use list_media_lists to discover existing work across MCP, REST, and the Medialyst app; preserve project/date filters while following page.next_cursor.
  • To build a list, call create_media_list with a prompt and target_list_size as a credit budget, plus a stable request_options.idempotency_key; optionally pass project_id, which additionally requires projects:manage. Poll get_media_list_job to a terminal status, then call get_media_list with include_rows: true and row_detail: "full".
  • Save and reuse the returned job_id and media_list_id; job and table reads are organization-scoped.
  • Use delete_media_list only when the user wants whole lists permanently removed. Put up to 50 returned ids in selector.keys; use dry_run: true to confirm the selection, then dry_run: false with a stable idempotency_key. It cancels linked active jobs and cannot be undone.
  • Use returned ids. Do not invent enrichment, media-list job, or media-list ids.
  • The MCP cannot mutate individual generated table rows, create share links, or send outreach. Review and sending stay in the Medialyst app, where the person whose reputation is on the line keeps final judgment.

Canonical media-list flow:

list_media_lists(filters?, cursor?)
  -> reuse an existing media_list_id, or:
create_media_list
  -> get_media_list_job until complete, failed, or cancelled
  -> get_media_list(media_list_id, include_rows=true, row_detail=full)
  -> continue with page.next_cursor until null
  -> optional cleanup: delete_media_list(selector.keys=[media_list_id], dry_run=false, idempotency_key=stable_key)

Canonical known-journalist input:

{
  "from": [
    {
      "type": "journalist_reference",
      "name": "Jane Doe",
      "publication": "The Daily Example"
    }
  ]
}

Canonical direct-email flow:

lookup_journalist(q = name + outlet)
  -> ambiguous: lookup_journalist(journalist_id = chosen candidate)
               or, if none is the person, lookup_journalist(q, find_live = true)
  -> checking: wait retry_after_seconds, call again with the same input
  -> found: return email with the outlet and affiliation_status
  -> not_found: say so; never guess an address

See Medialyst MCP for OAuth and API-key setup, the full tool surface, and troubleshooting.