HTTP RPC reference

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 }
  }'

curl -X POST https://api.sippet.ai/rpc/public/validate \
  -H "content-type: application/json" \
  -H "x-api-key: $SIPPET_SECRET_KEY" \
  -d '{
    "action": "create_contact",
    "input": {
      "fullName": "Ada Lovelace",
      "phoneE164": "+15555550123"
    }
  }'

/**
 * Represents the result of a validation RPC call.
 *
 * All validation actions return this same structure, indicating either
 * successful validation or a list of validation errors.
 *
 * @example
 * // Successful validation
 * const result: ValidationResult = { success: true };
 *
 * // Failed validation
 * const result: ValidationResult = {
 *   success: false,
 *   errors: [
 *     {
 *       type: "required",
 *       message: "is required",
 *       shortMessage: "Required field",
 *       vars: { field: "email" },
 *       fields: ["email"],
 *       path: []
 *     }
 *   ]
 * };
 */
export type ValidationResult =
  | { success: true }
  | { success: false; errors: AshRpcError[]; };

/**
 * Represents an error from an unsuccessful RPC call.
 *
 * This type matches the error structure defined in the AshTypescript.Rpc.Error protocol.
 *
 * @example
 * const error: AshRpcError = {
 *   type: "invalid_changes",
 *   message: "Invalid value for field %{field}",
 *   shortMessage: "Invalid changes",
 *   vars: { field: "email" },
 *   fields: ["email"],
 *   path: ["user", "email"],
 *   details: { suggestion: "Provide a valid email address" }
 * }
 */
export type AshRpcError = {
  /** Machine-readable error type (e.g., "invalid_changes", "not_found") */
  type: string;
  /** Full error message (may contain template variables like %{key}) */
  message: string;
  /** Concise version of the message */
  shortMessage: string;
  /** Variables to interpolate into the message template */
  vars: Record<string, any>;
  /** List of affected field names (for field-level errors) */
  fields: string[];
  /** Path to the error location in the data structure */
  path: string[];
  /** Optional map with extra details (e.g., suggestions, hints) */
  details?: Record<string, any>;
}

export async function whoAmI<Fields extends WhoAmIFields>(
  config: {
  fields: Fields;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<WhoAmIResult<Fields>>

{
  "action": "who_am_i",
  "fields": [
    "id"
  ]
}

export type WhoAmIFields = UnifiedFieldSelection<UserResourceSchema>[];

export type InferWhoAmIResult<
  Fields extends WhoAmIFields,
> = InferResult<UserResourceSchema, Fields>;

export type WhoAmIResult<Fields extends WhoAmIFields> = | { success: true; data: InferWhoAmIResult<Fields>; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateWhoAmI(
  config: {
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function issueOperatorAccessToken(
  config: {
  input: IssueOperatorAccessTokenInput;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<IssueOperatorAccessTokenResult>

{
  "action": "issue_operator_access_token",
  "input": {
    "operatorEmail": "<string>"
  }
}

export type IssueOperatorAccessTokenInput = {
  operatorEmail: string;
};

export type InferIssueOperatorAccessTokenResult = Record<string, any>;

export type IssueOperatorAccessTokenResult = | { success: true; data: InferIssueOperatorAccessTokenResult; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateIssueOperatorAccessToken(
  config: {
  input: IssueOperatorAccessTokenInput;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function listAiAgents<Fields extends ListAiAgentsFields, Config extends ListAiAgentsConfig = ListAiAgentsConfig>(
  config: Config & { fields: Fields }
): Promise<ListAiAgentsResult<Fields, Config["page"]>>

{
  "action": "list_ai_agents",
  "fields": [
    "id"
  ],
  "filter": {
    "id": {
      "eq": "<uuid>"
    }
  },
  "sort": "insertedAt",
  "page": {
    "limit": 20
  }
}

export type ListAiAgentsConfig = {
  fields: ListAiAgentsFields;
  filter?: AiAgentFilterInput;
  sort?: string;
  page?: (
    {
      limit?: number;
      offset?: number;
      count?: boolean;
    } | {
      limit?: number;
      after?: string;
      before?: string;
    }
  );
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
};

export type ListAiAgentsFields = UnifiedFieldSelection<AiAgentResourceSchema>[];

export type InferListAiAgentsResult<
  Fields extends ListAiAgentsFields | undefined,
  Page extends ListAiAgentsConfig["page"] = undefined
> = ConditionalPaginatedResultMixed<Page, Array<InferResult<AiAgentResourceSchema, Fields>>, {
  results: Array<InferResult<AiAgentResourceSchema, Fields>>;
  hasMore: boolean;
  limit: number;
  offset: number;
  count?: number | null;
  type: "offset";
}, {
  results: Array<InferResult<AiAgentResourceSchema, Fields>>;
  hasMore: boolean;
  limit: number;
  after: string | null;
  before: string | null;
  previousPage: string;
  nextPage: string;
  count?: number | null;
  type: "keyset";
}>;

export type ListAiAgentsResult<Fields extends ListAiAgentsFields, Page extends ListAiAgentsConfig["page"] = undefined> = | { success: true; data: InferListAiAgentsResult<Fields, Page>; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateListAiAgents(
  config: {
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function startAiAgentDraftTest(
  config: {
  input: StartAiAgentDraftTestInput;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<StartAiAgentDraftTestResult>

{
  "action": "start_ai_agent_draft_test",
  "input": {
    "draft": {}
  }
}

export type StartAiAgentDraftTestInput = {
  draft: Record<string, any>;
  contactId?: UUID;
  language?: string;
  profile?: "outbound_call" | "inbound_call" | "widget_voice";
  connection?: "browser" | "phone";
  testPhoneNumber?: string;
  executionMode?: "simulate" | "live";
};

export type InferStartAiAgentDraftTestResult = Record<string, any>;

export type StartAiAgentDraftTestResult = | { success: true; data: InferStartAiAgentDraftTestResult; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateStartAiAgentDraftTest(
  config: {
  input: StartAiAgentDraftTestInput;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function listBulkOutboundCalls<Fields extends ListBulkOutboundCallsFields, Config extends ListBulkOutboundCallsConfig = ListBulkOutboundCallsConfig>(
  config: Config & { fields: Fields }
): Promise<ListBulkOutboundCallsResult<Fields, Config["page"]>>

{
  "action": "list_bulk_outbound_calls",
  "fields": [
    "id"
  ],
  "filter": {
    "id": {
      "eq": "<uuid>"
    }
  },
  "sort": "insertedAt",
  "page": {
    "limit": 20
  }
}

export type ListBulkOutboundCallsConfig = {
  fields: ListBulkOutboundCallsFields;
  filter?: BulkOutboundCallFilterInput;
  sort?: string;
  page?: (
    {
      limit?: number;
      offset?: number;
      count?: boolean;
    } | {
      limit?: number;
      after?: string;
      before?: string;
    }
  );
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
};

export type ListBulkOutboundCallsFields = UnifiedFieldSelection<BulkOutboundCallResourceSchema>[];

export type InferListBulkOutboundCallsResult<
  Fields extends ListBulkOutboundCallsFields | undefined,
  Page extends ListBulkOutboundCallsConfig["page"] = undefined
> = ConditionalPaginatedResultMixed<Page, Array<InferResult<BulkOutboundCallResourceSchema, Fields>>, {
  results: Array<InferResult<BulkOutboundCallResourceSchema, Fields>>;
  hasMore: boolean;
  limit: number;
  offset: number;
  count?: number | null;
  type: "offset";
}, {
  results: Array<InferResult<BulkOutboundCallResourceSchema, Fields>>;
  hasMore: boolean;
  limit: number;
  after: string | null;
  before: string | null;
  previousPage: string;
  nextPage: string;
  count?: number | null;
  type: "keyset";
}>;

export type ListBulkOutboundCallsResult<Fields extends ListBulkOutboundCallsFields, Page extends ListBulkOutboundCallsConfig["page"] = undefined> = | { success: true; data: InferListBulkOutboundCallsResult<Fields, Page>; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateListBulkOutboundCalls(
  config: {
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function listCampaigns(
  config: {
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ListCampaignsResult>

{
  "action": "list_campaigns"
}

export type InferListCampaignsResult = Record<string, any>;

export type ListCampaignsResult = | { success: true; data: InferListCampaignsResult; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateListCampaigns(
  config: {
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function getCampaign(
  config: {
  input: GetCampaignInput;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<GetCampaignResult>

{
  "action": "get_campaign",
  "input": {
    "id": "<uuid>"
  }
}

export type GetCampaignInput = {
  id: UUID;
};

export type InferGetCampaignResult = Record<string, any>;

export type GetCampaignResult = | { success: true; data: InferGetCampaignResult; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateGetCampaign(
  config: {
  input: GetCampaignInput;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function pauseCampaign<Fields extends PauseCampaignFields | undefined = undefined>(
  config: {
  identity: UUID;
  fields?: Fields;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<PauseCampaignResult<Fields extends undefined ? [] : Fields>>

{
  "action": "pause_campaign",
  "identity": "<uuid>",
  "fields": [
    "id"
  ]
}

export type PauseCampaignFields = UnifiedFieldSelection<BulkOutboundCallResourceSchema>[];

export type InferPauseCampaignResult<
  Fields extends PauseCampaignFields | undefined,
> = InferResult<BulkOutboundCallResourceSchema, Fields>;

export type PauseCampaignResult<Fields extends PauseCampaignFields | undefined = undefined> = | { success: true; data: InferPauseCampaignResult<Fields>; }
| { success: false; errors: AshRpcError[]; }

;

export async function validatePauseCampaign(
  config: {
  identity: UUID | string;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function resumeCampaign<Fields extends ResumeCampaignFields | undefined = undefined>(
  config: {
  identity: UUID;
  fields?: Fields;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ResumeCampaignResult<Fields extends undefined ? [] : Fields>>

{
  "action": "resume_campaign",
  "identity": "<uuid>",
  "fields": [
    "id"
  ]
}

export type ResumeCampaignFields = UnifiedFieldSelection<BulkOutboundCallResourceSchema>[];

export type InferResumeCampaignResult<
  Fields extends ResumeCampaignFields | undefined,
> = InferResult<BulkOutboundCallResourceSchema, Fields>;

export type ResumeCampaignResult<Fields extends ResumeCampaignFields | undefined = undefined> = | { success: true; data: InferResumeCampaignResult<Fields>; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateResumeCampaign(
  config: {
  identity: UUID | string;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function endCampaign<Fields extends EndCampaignFields | undefined = undefined>(
  config: {
  identity: UUID;
  fields?: Fields;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<EndCampaignResult<Fields extends undefined ? [] : Fields>>

{
  "action": "end_campaign",
  "identity": "<uuid>",
  "fields": [
    "id"
  ]
}

export type EndCampaignFields = UnifiedFieldSelection<BulkOutboundCallResourceSchema>[];

export type InferEndCampaignResult<
  Fields extends EndCampaignFields | undefined,
> = InferResult<BulkOutboundCallResourceSchema, Fields>;

export type EndCampaignResult<Fields extends EndCampaignFields | undefined = undefined> = | { success: true; data: InferEndCampaignResult<Fields>; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateEndCampaign(
  config: {
  identity: UUID | string;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function listBulkOutboundCallEntries<Fields extends ListBulkOutboundCallEntriesFields, Config extends ListBulkOutboundCallEntriesConfig = ListBulkOutboundCallEntriesConfig>(
  config: Config & { fields: Fields }
): Promise<ListBulkOutboundCallEntriesResult<Fields, Config["page"]>>

{
  "action": "list_bulk_outbound_call_entries",
  "fields": [
    "id"
  ],
  "filter": {
    "id": {
      "eq": "<uuid>"
    }
  },
  "sort": "insertedAt",
  "page": {
    "limit": 20
  }
}

export type ListBulkOutboundCallEntriesConfig = {
  fields: ListBulkOutboundCallEntriesFields;
  filter?: BulkOutboundCallEntryFilterInput;
  sort?: string;
  page?: (
    {
      limit?: number;
      offset?: number;
      count?: boolean;
    } | {
      limit?: number;
      after?: string;
      before?: string;
    }
  );
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
};

export type ListBulkOutboundCallEntriesFields = UnifiedFieldSelection<BulkOutboundCallEntryResourceSchema>[];

export type InferListBulkOutboundCallEntriesResult<
  Fields extends ListBulkOutboundCallEntriesFields | undefined,
  Page extends ListBulkOutboundCallEntriesConfig["page"] = undefined
> = ConditionalPaginatedResultMixed<Page, Array<InferResult<BulkOutboundCallEntryResourceSchema, Fields>>, {
  results: Array<InferResult<BulkOutboundCallEntryResourceSchema, Fields>>;
  hasMore: boolean;
  limit: number;
  offset: number;
  count?: number | null;
  type: "offset";
}, {
  results: Array<InferResult<BulkOutboundCallEntryResourceSchema, Fields>>;
  hasMore: boolean;
  limit: number;
  after: string | null;
  before: string | null;
  previousPage: string;
  nextPage: string;
  count?: number | null;
  type: "keyset";
}>;

export type ListBulkOutboundCallEntriesResult<Fields extends ListBulkOutboundCallEntriesFields, Page extends ListBulkOutboundCallEntriesConfig["page"] = undefined> = | { success: true; data: InferListBulkOutboundCallEntriesResult<Fields, Page>; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateListBulkOutboundCallEntries(
  config: {
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function listCalls<Fields extends ListCallsFields>(
  config: {
  fields: Fields;
  filter?: CallFilterInput;
  sort?: string;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ListCallsResult<Fields>>

{
  "action": "list_calls",
  "fields": [
    "id"
  ],
  "filter": {
    "id": {
      "eq": "<uuid>"
    }
  },
  "sort": "insertedAt"
}

export type ListCallsFields = UnifiedFieldSelection<CallResourceSchema>[];

export type InferListCallsResult<
  Fields extends ListCallsFields,
> = Array<InferResult<CallResourceSchema, Fields>>;

export type ListCallsResult<Fields extends ListCallsFields> = | { success: true; data: InferListCallsResult<Fields>; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateListCalls(
  config: {
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function createCall<Fields extends CreateCallFields | undefined = undefined>(
  config: {
  input: CreateCallInput;
  fields?: Fields;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<CreateCallResult<Fields extends undefined ? [] : Fields>>

{
  "action": "create_call",
  "input": {
    "direction": "inbound",
    "fromNumber": "<string>",
    "toNumber": "<string>",
    "callUuid": "<string>"
  },
  "fields": [
    "id"
  ]
}

export type CreateCallInput = {
  direction: "inbound" | "outbound";
  fromNumber: string;
  toNumber: string;
  sipUsername?: string | null;
  callUuid: string;
  callSource?: string;
  outboundTrunkSource?: "default_sippet_trunk" | "custom_gateway" | null;
  status?: "initiated" | "ringing" | "waiting_for_operator" | "answered" | "completed" | "failed" | "busy" | "no_answer" | null;
  conversationId?: UUID | null;
  startedAt?: UtcDateTimeUsec | null;
  answeredAt?: UtcDateTimeUsec | null;
  mediaQualifiedAt?: UtcDateTimeUsec | null;
  callerSpokeAt?: UtcDateTimeUsec | null;
};

export type CreateCallFields = UnifiedFieldSelection<CallResourceSchema>[];

export type InferCreateCallResult<
  Fields extends CreateCallFields | undefined,
> = InferResult<CallResourceSchema, Fields>;

export type CreateCallResult<Fields extends CreateCallFields | undefined = undefined> = | { success: true; data: InferCreateCallResult<Fields>; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateCreateCall(
  config: {
  input: CreateCallInput;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function flagCallForReview<Fields extends FlagCallForReviewFields | undefined = undefined>(
  config: {
  identity: UUID;
  fields?: Fields;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<FlagCallForReviewResult<Fields extends undefined ? [] : Fields>>

{
  "action": "flag_call_for_review",
  "identity": "<uuid>",
  "fields": [
    "id"
  ]
}

export type FlagCallForReviewFields = UnifiedFieldSelection<CallResourceSchema>[];

export type InferFlagCallForReviewResult<
  Fields extends FlagCallForReviewFields | undefined,
> = InferResult<CallResourceSchema, Fields>;

export type FlagCallForReviewResult<Fields extends FlagCallForReviewFields | undefined = undefined> = | { success: true; data: InferFlagCallForReviewResult<Fields>; }
| { success: false; errors: AshRpcError[]; }

;

export async function validateFlagCallForReview(
  config: {
  identity: UUID | string;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ValidationResult>

export async function clearCallReviewFlag<Fields extends ClearCallReviewFlagFields | undefined = undefined>(
  config: {
  identity: UUID;
  fields?: Fields;
  headers?: Record<string, string>;
  fetchOptions?: RequestInit;
  customFetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}
): Promise<ClearCallReviewFlagResult<Fields extends undefined ? [] : Fields>>

{
  "action": "clear_call_review_flag",
  "identity": "<uuid>",
  "fields": [
    "id"
  ]
}

export type ClearCallReviewFlagFields = UnifiedFieldSelection<CallResourceSchema>[];

export type InferClearCallReviewFlagResult<
  Fields extends ClearCallReviewFlagFields | undefined,
> = InferResult<CallResourceSchema, Fields>;

export type ClearCallReviewFlagResult<Fields extends ClearCallReviewFlagFields | undefined = undefined> = | { success: true; data: InferClearCallReviewFlagResult<Fields>; }
| { success: false; errors: AshRpcError[]; }

;