Keryx API and MCP

Use your existing account, products, creative credit and saved work.

Connect your AI app

Add https://app.keryxmarketing.com/mcp as a remote MCP server. Start the connection in your client; it opens Keryx so you can sign in or create an account with Google or email/password. Complete email verification if asked, then approve the connection. You return to the client with the same account, workspace and credit as the website.

Use the existing account if you have one, including Google linked to an email account. Passwords and verification codes stay on Keryx. Connector installation, enabling tools or restarting the client may still be needed; reading this guide alone does not connect it.

Manage or revoke access in Connections. Product and creative permissions do not authorize campaign launches.

Use the HTTP API

The API base is https://app.keryxmarketing.com/api. Read the OpenAPI document for the supported operations and request schemas.

Use authorization code with S256 PKCE. Authorization metadata advertises registration, token and revocation endpoints. Request the exact resource https://app.keryxmarketing.com/api for HTTP or https://app.keryxmarketing.com/mcp for MCP; a token for one cannot be used at the other.

Send the access token as Authorization: Bearer …. Refresh tokens rotate: save the returned replacement and serialize refresh requests. Browser cookies and ID tokens are not API credentials.

Create your first ad

Use the customer's product website or store link and their direction. Ask for the product link if it is missing; the Keryx service website is not automatically the product to advertise. The agent can choose an approach from the request and product context without asking the customer to operate each tool.

  1. Use get_account and list_products (GET /v1/me and GET /v1/products) to find the connected workspace and reuse an existing product.
  2. For a new product, use discover_product (POST /v1/product-discovery/sessions) with its website or store URLs. Observe the returned session with get_product_discovery.
  3. Use add_product (POST /v1/products) with the saved discovery reference and the customer's authorized locations. Their instruction to add their own supplied product can provide that direction; don't invent ownership of newly discovered locations.
  4. Read get_creative_workspace for saved work and capabilities. Use add_concept for one idea, or start_concepts for three. Each named tool accepts its command fields in request; all use the same HTTP creative-workspace operation. Direction is optional; product context is used when omitted.
  5. To start from a finished image or video ad you made, reserve an upload at POST /v1/products/…/creative-workspace/uploads with its file name, JPEG, PNG, MP4 or MOV type and size, then PUT the file to the returned URL with the returned headers. Send add_concept with uploads naming each uploadId; several files must be sizes of one ad and all images or all videos. Keryx reads the idea from the ad and saves your image as an Image ad or your video as a Short video ad. In MCP, create_media_upload returns the same link.
  6. An idea is not a finished ad. Use create_formats with the exact saved idea pins and desired formats to create artwork. Read the same workspace for its saved progress and outputs. Use iterate_concept for an idea revision or revise_output for a saved ad.
  7. Use show_creative with the product ID and exact saved outputVersionIds to show an image, carousel, video or text preview in clients that support MCP Apps. Other clients receive the same saved content and a Keryx link. Use get_creative_media with an artifact's asset ID and content hash for a media URL. These links last sixty seconds; refreshing them reads the same saved media without generating another ad.

Retry without purchasing twice

Every mutation requires an Idempotency-Key. Keep the exact request body and key when a response is lost. Once accepted, read the saved operation. A terminal failure or an unknown provider outcome does not authorize a new paid attempt.

Reads start no creative work. Optional research or review failures preserve usable results under the same rules as the website. Creative requests use your existing Keryx balance.

Staff prospect preparation

Staff clients can explicitly request prospects:prepare alongside product and creative scopes during OAuth. This opens staff sign-in; ordinary customer connections do not receive this authority.

prepare_prospect prepares a product and unclaimed workspace from a recipient email and public product facts, without sending email or asserting recipient ownership. Retain its workspaceId and pass it to existing creative tools (HTTP: X-Workspace-Id). Preparation uses operator credit.

The returned claimUrl is for later authorized outreach. Its recipient uses normal signup/sign-in and verified email to claim the saved work, ending the operator’s preparation access. New recipient creative work uses their workspace’s credit. This flow does not create recipient credentials or authorize campaign launch.

Trace a request

HTTP and MCP responses include X-Correlation-Id in their headers. Shared service logs use the same reference. Keep this reference and any returned operation ID when reporting a problem. A caller can supply X-Correlation-Id to connect related requests. It is a debugging reference, separate from the mutation's stable idempotency key.