Agent discovery

The safe discover, sign up, connect, validate, confirm, and schedule workflow for AI agents using posterly.

Last updated Sep 9, 2026Updated this week

posterly exposes a complete public discovery graph so an AI agent can understand the product before asking a user to configure credentials.

1. Discover posterly

Start with one of these public resources:

Do not scrape the dashboard to infer capabilities. Use list_platforms, get_platform_schema, or the OpenAPI contract for the current platform rules.

2. Start paid agent access

API and MCP access require a paid posterly plan plus the API add-on. Send the user to agent signup, or use the public MCP signup tools before an API key exists.

The signup flow never returns an API key before billing is active. The user completes checkout, password setup, and any provider authorization in their browser.

3. Authenticate and confirm identity

After the user supplies a dashboard-created API key or completes an approved OAuth handoff:

  1. call whoami;
  2. inspect the returned workspaces and scopes;
  3. call list_accounts;
  4. ask which account and workspace the user intends to operate.

Never print, log, or place an API key in a post payload.

4. Connect a social account when needed

If the required account is absent, create a connection session for the chosen platform. Give the user the returned connect_url and poll the session. Provider OAuth and credentials stay in the user's browser; the agent receives bounded status updates.

Credential-based platforms (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) can also be connected headlessly: call GET /api/v1/connect/{platform} (or MCP get_connect_link) to discover the required credential_fields, then submit them with POST /api/v1/connect/{platform}/credentials (or MCP connect_account). Prefer scoped secrets such as app passwords, bot tokens, webhook URLs, and API tokens over primary passwords, and tell the user that any credential they share passes through the conversation.

5. Get media into posterly storage

Chat attachments never become MCP arguments. Pick a path that matches the client:

  • Small public URL: upload_media_from_url, or pass media_url on validate/create. Server fetch caps: about 5MB relay, 60MB hard cap. Large R2/S3 URLs fail with remote_media_too_large.
  • Small file as JSON: hosted upload_media (base64). This hits the Vercel ~4MB request body on /api/mcp and /api/v1/media/upload. Use it for small images only.
  • Large local file on a machine the agent can read: stdio upload_media with file_path, or create_signed_upload then PUT the bytes to upload_url. That PUT goes to object storage and does not hit the 4MB Vercel body. Plan video caps are Starter 500MB, Pro 750MB, Power 1GB, Agency 4GB.
  • ChatGPT web / Claude.ai: chat paperclips never reach MCP, and the model cannot PUT a laptop file. Call create_media_drop, send the user drop_url (https://www.poster.ly/drop/<token>, no dashboard login), wait, then list_media (optionally with drop_session_id), then validate/create. HEIC and PDF are rejected. Plan video caps still apply. This is not create_signed_upload. Codex, Claude Code, and Cursor can still use file_path or create_signed_upload then PUT.

Then gather the final account, caption, schedule, media URL from the step above, post type, platform settings, and workspace. Then use either:

  • MCP validate_post; or
  • POST /api/v1/posts with "dry_run": true.

Dry-run performs the same normalization and platform validation as live create, but it does not create a post, copy remote media, consume post-item or storage quota, reserve X quota, emit webhooks, or enqueue publishing.

Third-party media can produce remote_media_not_materialized. This means the URL was checked but not copied; live create still performs storage copy and final byte validation.

6. Show the preview and obtain confirmation

Resolve validation errors and warnings. Show the user:

  • account and platform;
  • complete final caption or thread;
  • scheduled time in the user's timezone;
  • attached media;
  • platform settings;
  • target workspace.

Obtain explicit confirmation for that exact post. Validation is not permission to publish.

7. Schedule the live post

After confirmation, call MCP create_post with confirm: true, or make the live REST request with dry_run omitted. Reuse the validated payload. Return the post ID, status, schedule, and posterly dashboard link.

8. Report product issues or private telemetry (optional)

Keep these two paths separate:

  • Public product board: when the human asks to report a bug or suggest a feature, call MCP submit_product_feedback or POST /api/v1/feedback with confirm: true after they approve the title and category. This lands on the same board as the dashboard Feedback page (5 submissions/day per API key).
  • Private ops telemetry: after a concrete tool success, error, or abandoned workflow, call MCP submit_agent_feedback or POST /api/v1/agent-feedback. Do not use this for roadmap ideas, and never put secrets, prompts, captions, media URLs, or personal data in the payload.

Schemas and examples live in the OpenAPI document (ProductFeedbackRequest, AgentFeedbackRequest).

For complete field documentation, continue with the REST API, MCP, or CLI guide.

Previous
CLI