Your automation. One conversation.

01Before you start

Start with an account and a conversation in the Pushyou internal test app you were invited to. Web sign-in requires QR approval in that app. The setup guide lets you choose a conversation and verify delivery.

Create a program connection in Settings → Connections. Grant only the conversations and operations it needs. Keys are shown once. Selected-room access cannot create a new room; that requires all-room access and conversations:write.

02Authentication

Run these commands in Bash or zsh on your computer or server. Store the key in your runtime’s secret configuration. Never embed it in browser code, a URL, or a published conversation view. MCP OAuth tokens cannot authenticate REST requests.

export PUSHYOU_API_URL='https://asia-northeast3-pushyou-prod.cloudfunctions.net/pushyouApi'
export PUSHYOU_MEDIA_URL='https://asia-northeast3-pushyou-prod.cloudfunctions.net/pushyouMedia'

printf 'Pushyou API key: ' >&2
IFS= read -r -s PUSHYOU_API_KEY
printf '\n' >&2
export PUSHYOU_API_KEY

curl --fail-with-body --silent --show-error \
  -X GET "$PUSHYOU_API_URL/v1/me" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY"

03Send your first message

Choose an existing conversation

Check id, permissions and conversation_ids in the account response. A null conversation_ids value means all conversations. List permitted rooms, then replace YOUR_CONVERSATION_ID with one of their IDs. Reading this list requires conversations:read.

curl --fail-with-body --silent --show-error \
  -X GET "$PUSHYOU_API_URL/v1/conversations?limit=20" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY"

export PUSHYOU_CONVERSATION_ID='YOUR_CONVERSATION_ID'

curl --fail-with-body --silent --show-error \
  -X POST "$PUSHYOU_API_URL/v1/conversations/$PUSHYOU_CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"id":"docs-message-01","text":"Pushyou connection verified.","notify":true}'

{
  "conversation_id": "YOUR_CONVERSATION_ID",
  "message_id": "docs-message-01",
  "duplicate": false
}

Use a stable ID for each logical message. Sending the same ID and content again returns HTTP 200 with duplicate: true. A different payload for the same ID returns 409. Use a new ID for a new message.

Message fields

Conversation, message and history lists use limit (1–100, default 50) and before=next_cursor. Keep filters when paging; stop when next_cursor is null. Events instead use an ascending numeric after cursor. Reads do not mark messages as read in the app.

04Replies & execution

Reply in the app, then fetch events. After actually handling an ordinary reply or action, save the result, send its ACK, and persist next_cursor. ACK does not remove an event or claim exclusive execution. Use one ordinary responder per room, or coordinate consumers yourself.

curl --fail-with-body --silent --show-error \
  -X GET "$PUSHYOU_API_URL/v1/conversations/$PUSHYOU_CONVERSATION_ID/events?after=0" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY"

curl --fail-with-body --silent --show-error \
  -X POST "$PUSHYOU_API_URL/v1/conversations/$PUSHYOU_CONVERSATION_ID/events/YOUR_EVENT_ID/ack" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{}'

Request approval

curl --fail-with-body --silent --show-error \
  -X POST "$PUSHYOU_API_URL/v1/conversations/$PUSHYOU_CONVERSATION_ID/tasks" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"id":"docs-report-01","title":"Review the weekly report","category_id":"reports","fields":[{"id":"notes","label":"Review notes","type":"multiline","required":false}]}'

Tasks track approval and execution together. After the owner approves, a worker reads events with task_protocol=1, persists its execution token, claims the attempt, and keeps the claim alive with heartbeats. It saves the actual result before complete. Task completion also acknowledges the event; a standalone ACK cannot finish a pending task.

Webhooks

Signed outbound webhooks are also supported. Configure them in the mobile app’s Response webhooks settings. Verify the original body signature and deduplicate delivery IDs. HTTP 2xx confirms receipt, not task completion. The downloadable workflow guide includes the signature and retry contract.

05Files & views

Files use a separate media endpoint and the same REST program key with media:write or media:read. Upload original bytes first, then attach the returned ID to a message in the same room. File URLs are private and require authorization. Images are limited to 10 MiB; videos to 25 MiB.

curl --fail-with-body --silent --show-error \
  "$PUSHYOU_MEDIA_URL/v1/media/docs-image-01?conversation_id=$PUSHYOU_CONVERSATION_ID" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY" \
  -H 'Content-Type: application/octet-stream' \
  -H 'X-Pushyou-Filename: review.png' \
  --data-binary @review.png

curl --fail-with-body --silent --show-error \
  -X POST "$PUSHYOU_API_URL/v1/conversations/$PUSHYOU_CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"id":"docs-attachment-01","text":"Please review this image.","attachment_ids":["docs-image-01"]}'

MCP uses pushyou_prepare_media_upload. Supply media_id, filename, content_type, byte size and SHA-256. POST the original bytes to the returned upload.url with its exact file-specific headers within five minutes, then send attachment_ids. The same preparation is available through REST. Do not substitute an account key or MCP OAuth token for the upload grant.

Publish an optional report, actions or HTML view with PATCH …/view and {"view": CARD}; {"view": null} removes it. The view opens from its conversation. HTML is isolated: no external network, app credentials or browser storage. Declare actions explicitly; they return events to the same room.

Card =
  { type: "report", title: string, items: { title: string, body?: string, label?: string }[] }
| { type: "actions", title: string, body?: string, actions: { id: ID, label: string }[] }
| { type: "html", title: string, html: string, height?: integer, actions?: { id: ID, label: string }[] }

Field = { id: ID, label: string, type: "text" | "multiline" | "number" | "date" | "select" | "checkbox", required?: boolean, options?: string[], min?: number, max?: number }

06Endpoint reference

Paths are relative to the base shown for each group. Use a Bearer program key unless a file-specific upload grant is specified. Expand a row for its request shape. Placeholder IDs must be replaced with your own.

{ media_id: ID, filename: string, content_type: string, size: integer, sha256: string }

GET /v1/me
→ { id, key_scope, permissions, conversation_ids }

{ id: ID, name: string, description?: string, kind?: string, view?: Card }

?limit=20&before=CURSOR
→ { conversations, next_cursor }

GET /v1/conversations/ROOM_ID
→ { conversation }

{ name?: string, description?: string, pinned?: boolean, active?: boolean, view?: Card | null }

{ id: ID, text?: string, attachment_ids?: ID[], card?: Card | null, notify?: boolean }

?limit=20&before=CURSOR
→ { messages, next_cursor }

GET /v1/conversations/ROOM_ID/messages/MESSAGE_ID
→ { message }

GET /v1/conversations/ROOM_ID/events/head
→ { cursor }

GET /v1/conversations/ROOM_ID/receiver-status
→ { receivers, checked_at }

{ sequence: positive_integer, state: "starting" | "receiving" | "processing" | "retrying" | "paused" | "stopped" | "needs_review" | "delivery_pending" }
instance_id: UUID v4

?after=0
?after=0&task_protocol=1
→ { events, next_cursor }

{}
→ { ok: true }

GET /v1/conversations/ROOM_ID/view
→ { view: Card | null }

{ view: Card | null }

?limit=20&before=CURSOR
&category_id=reports&conversation_id=ROOM_ID
&kind=received&status_group=attention
&result_pending=true
kind: received | action | saved
status_group: attention | progress | problems | complete
→ { history, next_cursor }

{ id: ID, title: string, body?: string, category_id?: ID, fields?: Field[], inputs?: object, expires_at?: integer, result_requires_review?: boolean }

GET /v1/conversations/ROOM_ID/tasks/TASK_ID
→ { task }

GET /v1/conversations/ROOM_ID/tasks/TASK_ID/versions
→ { versions: [{revision, title, body, fields, inputs, created_at, change_request}] }

{ request_id: ID, expected_revision: integer, change_request_id?: ID, body: string, title?: string, fields?: Field[], inputs?: object }
Only pending or changes_requested tasks can be revised. Approval is required for every new version.

{ request_id: ID, attempt: integer, execution_token: string }

{ request_id: ID, attempt: integer, execution_token: string }

{ request_id: ID, attempt: integer, execution_token: string, status: "succeeded" | "failed" | "needs_review", result: string, result_links?: [{label: string, url: HTTPS_URL}] }

GET /v1/conversations/ROOM_ID/actions
→ { actions }

{ title: string, description?: string, fields: Field[], category_id?: ID, active?: boolean, expected_revision?: ID }

POST upload.url
Headers: upload.headers
Body: original file bytes

Content-Type: application/octet-stream
X-Pushyou-Filename: URI_ENCODED_FILENAME
Body: original file bytes

Range: bytes=0-65535 (optional)
→ original file bytes

HEAD /v1/media/MEDIA_ID
→ Content-Type, Content-Length, Accept-Ranges

DELETE /v1/media/UNATTACHED_MEDIA_ID

07Troubleshooting

REST failures return a non-2xx status and {"error": "…"}. MCP tool failures are reported by the client; check the structured error and whether the connection still has permission.