References

Some capabilities create something you come back to later: an email you sent, a post you published, a monitor you set up. Those calls return a ref. Pass that ref to the follow-up capability to act on the same thing.

Send, then check

const sent = await p.email.send(
  { from: "shop@example.com", to: "buyer@example.com", subject: "Your receipt", text: "Thanks!" },
  { idempotencyKey: "order-1042-receipt" },
);
// { status: "queued", ref: "ref_01ARZ3NDEKTSV4RRFFQ69G5FAV" }

const delivery = await p.email.status({ ref: sent.ref });
// { status: "delivered", updatedAt: "2026-10-06T10:00:00.000Z" }

The same over HTTP:

curl https://api.pramaan.dev/v1/capabilities/email.status \
  -H "Authorization: Bearer $PRAMAAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref": "ref_01ARZ3NDEKTSV4RRFFQ69G5FAV"}'

Store the ref next to your own record (the order, the message) so you can look it up later.

Which capabilities use a ref

This call returns a `ref`	Pass it to
`email.send`	`email.status`
`sms.send`	`sms.status`
`social.post.publish`	`social.post.get`, `social.post.analytics`
`web.monitor.create`	`web.monitor.delete`
`deploy.deployment.create`	`deploy.deployment.get` (which also takes the deployment `id`)

Each capability’s reference page shows the ref field in its request or result.

Refs on list rows

Some lists return a ref on every row, so you can act on a row you did not create in this API call by call (a draft you list, then send). These start with rh_ and are passed exactly like any other ref. The same row gives the same ref each time you list it.

Rules

A ref is an opaque string that starts with ref_ or rh_. Don’t parse it or build one yourself. It can be up to 1,027 characters long.
A ref belongs to your account. Nobody else can use it.
A ref only works with the follow-ups of the call that returned it. An email’s ref passed to sms.status is refused.
A ref_ reference does not expire. A row’s rh_ reference normally does not either; where one does, the list’s reference page says so. If the thing behind it is gone (a deleted monitor), the follow-up fails with not_found.
Retrying a call with the same Idempotency-Key returns the same ref.
ref is optional in results: a call that fails returns none, and in rare cases a successful call has nothing to refer to. Check for it before you store it.
A follow-up on your own connected account still needs that connection to be in place.

Errors

Status	Code	When
`400`	`invalid_request`	`ref` is missing or not a reference, or it refers to a different kind of thing
`404`	`not_found`	No such reference in your account (“Reference not found.”)

See errors for the full list.

Get started

Guides

Tools

Send, then check

Which capabilities use a ref

Refs on list rows

Rules

Errors

​Send, then check

​Which capabilities use a ref

​Refs on list rows

​Rules

​Errors

Send, then check

Which capabilities use a ref

Refs on list rows

Rules

Errors