Agent discovery

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:

• llms.txt, concise product and link index
• llms-full.txt, deterministic agent reference
• OpenAPI 3.1, REST request and response schemas
• API reference, interactive API documentation
• MCP server card, hosted and stdio transport metadata
• Agent skills index, task-oriented instructions
• MCP setup, client configuration
• Smithery listing, managed hosted MCP connection with posterly OAuth

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.

5. Build and validate the complete post

Gather the final account, caption, schedule, media, 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.

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