Set up an agent to publish

An agent does not need a Syndroo package. It needs a URL, a Bearer token, and instructions about when to send a request. This page writes out that workflow, including the parts a client owns and the parts the API owns, so the two are not confused.

Access methods and their status

This is the whole compatibility record. A method is listed as not verified until there is a reproducible setup and a recorded test.

Nothing on this page has been exercised end to end with a real client in a recorded run. It describes the API contract and the safe client behaviour around it, not a verified integration.

The manual HTTP workflow

1. Prove the service answers

   Health needs no authentication, so check it before involving any credential. Set the URL first:

   export SYNDROO_URL="https://your-worker.your-subdomain.workers.dev"
   curl "$SYNDROO_URL/health"

   Expected: {"status":"ok"}. This endpoint always answers 200 while the Worker is running, including in maintenance mode. Maintenance mode only rejects new posts: POST /v1/posts then returns 503 with SERVICE_UNAVAILABLE, and reads keep working.

2. Give the client the credential out of band

   Put SYNDROO_API_KEY in the environment or secret store the agent process reads. Do not paste the key into a prompt, a chat transcript, an issue, a screenshot or a log line. The key can publish, so it deserves the same handling as a password.

   export SYNDROO_URL="https://your-worker.your-subdomain.workers.dev"
   export SYNDROO_API_KEY="the-secret-your-worker-has"

3. Draft and preview in the client

   Let the agent write the text and show it to you, per platform. Two things are worth stating plainly: the draft is produced by your agent, not by Syndroo, and the preview is a client feature. The API has no preview or approval endpoint, and it accepts whatever a confirmed request contains.

   Keep each platform's own limit in view while drafting: the candidate enforces 300 Unicode code points and 3,000 UTF-8 bytes for Bluesky, 500 characters for Threads, 280 weighted characters for X, 4,096 code points for Tumblr, and at most 3,000 UTF-16 units after escaping for LinkedIn. Each platform guide records its own limit and its own counting rule.

4. Confirm before anything is sent

   A person approves the text. This is a workflow rule for your client, not a service feature. It is the only thing standing between a model's suggestion and a public post.

5. Send one request with a stable key

   Use one Idempotency-Key per logical post, derived from content the client can reproduce (a release tag, a commit SHA, a job id). The same key with the same body returns the original result; the same key with different text is rejected with 409.

   curl -X POST "$SYNDROO_URL/v1/posts" \
     -H "Authorization: Bearer $SYNDROO_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: agent-run-2291" \
     --data '{
       "content": "Nightly ingest finished: 41,208 rows reconciled, 0 quarantined records.",
       "platforms": ["bluesky", "threads"]
     }'

6. Treat HTTP 202 as accepted, not published

   The reply is {"id": "post_...", "status": "queued"} (or "scheduled"). HTTP 202 does not confirm platform success, and it describes the state when the Worker accepted the request: by the time the response reaches you, a fast Queue consumer may already have published the post. Only the post's own status tells you what happened, so poll it until it is terminal.

   curl -H "Authorization: Bearer $SYNDROO_API_KEY" \
     "$SYNDROO_URL/v1/posts/post_..."

   Terminal post statuses are published, partial and failed. While a post is queued or publishing, wait and ask again instead of sending a new request.

7. Read failures per platform

   Each publication entry carries status, attempts, errorCode, errorMessage, errorAmbiguous, and the identifiers the platform returned. errorAmbiguous: true means the write may have reached the platform: stop, check by hand, and never resend automatically.

An instruction block you can adapt

This is a starting point for your own agent's instructions. It encodes the guardrails above; adjust the platform list and the tone, and keep the safety rules.

You publish social posts through a self-hosted Syndroo Worker.

Endpoint: $SYNDROO_URL (set in my environment; do not print it)
Auth: send the header "Authorization: Bearer $SYNDROO_API_KEY" (also from my environment)

Rules:
1. Never publish without showing me the exact text per platform and getting my yes.
2. One logical post, one Idempotency-Key. Reuse the key only when retrying the identical body.
3. Treat HTTP 202 as "accepted", never as "published". Confirm with
   GET /v1/posts/{id} until the status is published, partial or failed.
4. If a publication has errorAmbiguous true, tell me to check the platform by hand.
   Do not resend it, and do not send a new key for the same text.
5. If one platform fails and others published, retry nothing on my behalf; report per platform.
6. Never put the API key, or any platform token, in a prompt, a log, a commit or an issue.

Credential and secret handling

• SYNDROO_API_KEY is a publishing credential. It is not a read-only key. Treat anyone who has it as able to publish through your Worker.
• Platform credentials stay in the Worker. Bluesky, Threads, X, Tumblr and LinkedIn secrets are configured on your deployment; clients never hold them.
• The client holds one secret. The agent process needs the Syndroo URL and the API key, and nothing else.
• Rotation is replacing a secret. Change the value on the Worker, then update the environment your client reads. There is no token-issuing flow in this candidate.
• Nothing is sent to Syndroo by the website. The marketing demo is simulated and performs no request.

Response handling reference

What is not verified yet

• No Syndroo-authored skill, plugin or tool package exists, and none has been test-installed.
• No client-specific setup has been recorded: this page documents the HTTP workflow, not a tested client integration.
• No platform has a live-account acceptance record. Bluesky and Threads are mock-tested locally; X, Tumblr and LinkedIn are experimental.
• The Worker has not been deployed or published as a release in this candidate.

Next steps

• Publish your first post - one platform, end to end.
• HTTP API reference - every field, status and error code.
• Call Syndroo from CI or a script - the same workflow without a person in the loop, and why the key still matters.
• Ambiguous outcomes - why an unknown result is never resent automatically.