> ## Documentation Index
> Fetch the complete documentation index at: https://sippet.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP RPC API overview

> How to call Sippet's org API directly over the public RPC transport.

## What RPC means

RPC stands for Remote Procedure Call.

In a typical REST API, the URL and HTTP method define the operation:

* `GET /contacts`
* `POST /calls`
* `PATCH /contacts/:id`

In Sippet's RPC API, you send requests to a small fixed set of endpoints and choose the operation by sending an `action` in the JSON body:

* `POST /rpc/public/run` with `"action": "list_contacts"`
* `POST /rpc/public/run` with `"action": "create_call"`

That means:

* the HTTP transport stays consistent
* the action name describes the operation
* input, result, and field-selection types can map directly to generated SDK helpers

## What this page is for

Use the HTTP RPC API when your backend needs to call Sippet directly with a secret key.

If you are building a browser calling experience with voice, sockets, or live call events, use the frontend SDK docs instead:

* Frontend SDK overview: `/sdk-js/introduction`
* Realtime session tokens: `/guides/realtime-session-tokens`

If you are configuring Sippet itself for your org, use the console docs instead:

* Console overview: `/`
* AI agents: `/console/ai-agents`
* Integrations: `/console/discord-integration`

## Endpoints

* Run actions with `POST /rpc/public/run`
* Validate payloads with `POST /rpc/public/validate`

## Request shape

Every RPC request is a JSON object with an `action` key and the payload keys that action supports.

Common keys:

* `action`
  The RPC function you want to run, for example `list_contacts` or `create_call`.
* `input`
  The main input object for the action. Use this for values you are creating, updating, or submitting.
* `identity`
  A lookup object that identifies which existing record the action should target. This is commonly used for update or delete-style actions.
* `fields`
  The fields you want returned in the success response. This lets you request only the data your integration needs.
* `filter`
  Conditions used to narrow list or read actions, for example “only contacts with this phone number”.
* `sort`
  The ordering for list results, for example newest first or alphabetically by name.
* `page`
  Pagination options for list actions, such as page size or cursor information.
* `metadataFields`
  Extra metadata to include when an action exposes metadata separately from the main `data` payload.

## Example run request

```bash theme={null}
curl -X POST https://api.sippet.ai/rpc/public/run \
  -H "content-type: application/json" \
  -H "x-api-key: $SIPPET_SECRET_KEY" \
  -d '{
    "action": "list_contacts",
    "fields": ["id", "fullName"],
    "page": {
      "limit": 20
    }
  }'
```

## Response shape

All public RPC responses use the same envelope:

```ts theme={null}
type RpcResponse<T> =
  | { success: true; data: T }
  | { success: false; errors: AshRpcError[] };
```

Use `/rpc/public/validate` when you want to validate payloads before executing them. Validator requests use the same `action` and payload keys as their matching `/rpc/public/run` request.

## Reference pages

* Full HTTP RPC function reference: `/sdk-js/rpc-actions`
* Frontend SDK overview: `/sdk-js/introduction`
* Console docs: `/`