AI & Integrations

Agent Skill

A ready-to-use SKILL.md that teaches coding agents how to publish with the Relaycast API.

Coding agents work best when they have short, focused instructions for a task. The file below packages everything an agent needs to publish with Relaycast: the three API calls, the request format and the rules that trip people up. Copy it into your project and the agent can use the API without reading the full docs first.

The skill file

SKILL.md

---
name: relaycast
description: Publish or schedule social media posts to X, Instagram, Facebook, LinkedIn, TikTok, YouTube, Threads, Pinterest, Bluesky and Google Business Profile with the Relaycast REST API. Use when asked to post, cross-post, schedule or check the status of social media posts.
---

# Relaycast

REST API for publishing one post to many social accounts.

- Base URL: https://social-publish-api.onrender.com
- Auth: header `x-access-key: $RELAYCAST_API_KEY` (or `Authorization: Bearer $RELAYCAST_API_KEY`).
  Read the key from the environment. Never print it, hard-code it or commit it.
- JSON request and response bodies. Errors look like `{ "error": { "code", "message", "details?" } }`.
- Full docs: https://social-publish-kappa.vercel.app/llms.txt

## Workflow

1. List accounts: `GET /v1/accounts` -> `{ "data": [{ "id", "platform", "handle", "status", ... }] }`.
   Only accounts with `status: "active"` can be posted to. Never guess account IDs.
2. Publish: `POST /v1/posts` with an `Idempotency-Key` header (a unique string per logical post):
   {
     "content": "Text shared by all targets",
     "targets": [{ "accountId": "<id>", "content": "optional per-account text", "options": { } }],
     "media": [{ "url": "https://public.example.com/image.jpg", "type": "image", "altText": "..." }],
     "publishNow": true
   }
   For later, replace `publishNow` with `"scheduledFor": "2026-10-12T09:00:00Z"`.
   Returns 201 with `{ "data": post }` (200 if the idempotency key was already used).
3. Check results: `GET /v1/posts/{id}`. Publishing is asynchronous. Each entry in `data.targets`
   has `status` (queued | publishing | published | failed), `externalUrl` when live, and
   `errorCode` / `errorMessage` when failed. Post `status` ends as published | partial | failed.

## Rules

- `targets`: 1-20 accounts. `content`: 1-10,000 characters, but each platform has a lower limit.
- Send exactly one of `publishNow: true` or `scheduledFor`. `scheduledFor` must be ISO 8601 with
  a timezone (`Z` or `+02:00`) and in the future.
- Media: up to 10 items, `type` is image | video | document (PDF, LinkedIn only). URLs must be
  public https URLs the platform can download at publish time (no localhost, no login).
  `media://<id>` references to the user's media library also work. There is no upload endpoint.
- Platform-specific settings go in `targets[].options` (e.g. TikTok requires `privacyLevel`,
  YouTube takes `title` and `visibility`). See https://social-publish-kappa.vercel.app/docs/platform-options.md
- Each target costs 1 credit (refunded if it fails). 402 `insufficient_credits` means stop.
- 400 `validation_error` with `details` keyed by account ID: fix the listed fields and retry.
  Do not retry other 4xx errors unchanged. Retry 429/5xx/network errors with the SAME
  Idempotency-Key.
- Connecting accounts (except Bluesky), uploading media, and editing or deleting posts happen in
  the dashboard (https://social-publish-kappa.vercel.app/dashboard), not the API. Tell the user when they need to do this.
- Confirm the final text, accounts and time with the user before publishing.

## Example

curl -X POST https://social-publish-api.onrender.com/v1/posts \
  -H "x-access-key: $RELAYCAST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-2026-10-12" \
  -d '{"content":"We are live!","targets":[{"accountId":"<id>"}],"publishNow":true}'

The description in the front matter is what an agent reads to decide when the skill applies, so keep it specific to publishing.

Set up the access key

The skill reads the key from the RELAYCAST_API_KEY environment variable. Create a key at https://social-publish-kappa.vercel.app/dashboard/api-keys and export it in the shell or environment the agent runs in:

export RELAYCAST_API_KEY="sp_live_..."

Don't paste the key into the skill file or the chat. Anything in a file in your repository or in the conversation can end up in logs or commits. Use a dedicated key for agents so you can revoke it on its own.

Where to put it

Different agents look for instructions in different places. The content is the same, only the location changes.

Claude Code

Claude Code loads skills from a SKILL.md file inside a folder under .claude/skills/. Save the file as:

.claude/skills/relaycast/SKILL.md

Put it in your project to share it with your team through version control, or in ~/.claude/skills/relaycast/SKILL.md to use it in every project. Claude reads the description and loads the skill when a task matches.

Codex and other agents that read AGENTS.md

Many coding agents, including Codex, read an AGENTS.md file at the root of the repository. Paste the body of the skill (everything after the front matter) into a ## Relaycast section of AGENTS.md.

Cursor

Cursor uses project rules. Create a rule file under .cursor/rules/ (for example .cursor/rules/relaycast.mdc) with the body of the skill, and set the rule's description so Cursor applies it to social publishing tasks. Cursor also reads AGENTS.md.

Other tools

For any other assistant, add the body of the skill to whatever custom-instructions or rules file it supports, or attach it as context. Check that tool's documentation for the exact file name and location, since these conventions change.

Keep it up to date

The skill is a summary. For details, point the agent at the Markdown docs: every page is available as Markdown, and https://social-publish-kappa.vercel.app/llms.txt indexes them. See llms.txt & Markdown Docs.

This page is also available as Markdown.