rest-tools — @personaai/sdk

Generated field tables for rest-tools — do not edit

Generated from sdk/typescript/dist/typedoc.json — do not edit. Regenerate with node platform/scripts/typedoc-resources.mjs.

rest-tools

Auth: Requires Authorization: Bearer <keyId>.<secret> (server-side). For per-user calls add x-persona-external-user-id. See .

REST tools are code-first tools via defineRestTool (zod) served as GET {mountPath}/rest-tools/manifest and discovered live as a Source.

Example

TypeScript

import { defineRestTool } from '@personaai/sdk/rest-tools'; import { z } from 'zod';const getProfile = defineRestTool({ name: 'Get learner', method: 'GET', args: z.object({ userId: z.string() }), url: t => `https://api.example.com/users/${t.arg('userId')}` });

import { defineRestTool } from '@personaai/sdk/rest-tools'; import { z } from 'zod';const getProfile = defineRestTool({ name: 'Get learner', method: 'GET', args: z.object({ userId: z.string() }), url: t => `https://api.example.com/users/${t.arg('userId')}` });

cURL

bash

curl https://api.persona.hasanraiyan.me/api/v1/developer/rest-tools -H "Authorization: Bearer $PERSONA_CREDENTIAL" | jq .

curl https://api.persona.hasanraiyan.me/api/v1/developer/rest-tools -H "Authorization: Bearer $PERSONA_CREDENTIAL" | jq .

Response

`RestApiTool`

A no-code REST API tool an Agent can call. Goes through toSafeJson() — secretRef's underlying value is never returned, only hasSecret.

Source: types/restTool.ts:39

Interface

Field	Type	Description
`_id`	`string`	— _ `types/restTool.ts:40`_
`domain`	`string`	— _ `types/restTool.ts:41`_
`ownerType`	`"PersonaUser" \| "Project" \| "ExternalUser"`	— _ `types/restTool.ts:42`_
`ownerId?`	`string`	— _ `types/restTool.ts:43`_
`externalOwnerId?`	`string`	— _ `types/restTool.ts:44`_
`name`	`string`	— _ `types/restTool.ts:45`_
`description?`	`string`	— _ `types/restTool.ts:46`_
`method`	`RestToolMethod`	— _ `types/restTool.ts:47`_
`url`	`string`	— _ `types/restTool.ts:48`_
`queryParams`	`RestToolParamRow[]`	— _ `types/restTool.ts:49`_
`headers`	`RestToolParamRow[]`	— _ `types/restTool.ts:50`_
`bodyMode`	`RestToolBodyMode`	— _ `types/restTool.ts:51`_
`bodyTemplate?`	`string`	— _ `types/restTool.ts:52`_
`paramDescriptors`	`RestToolParamDescriptor[]`	— _ `types/restTool.ts:53`_
`authType`	`RestToolAuthType`	— _ `types/restTool.ts:54`_
`secretRef?`	`string`	Present only when `authType: 'bearerSecret'`. — _ `types/restTool.ts:56`_
`hasSecret`	`boolean`	— _ `types/restTool.ts:57`_
`responseMappings`	`RestToolResponseMapping[]`	— _ `types/restTool.ts:58`_
`isEnabled`	`boolean`	— _ `types/restTool.ts:59`_
`lastTestedAt?`	`string \| null`	— _ `types/restTool.ts:60`_
`lastTestedStatus?`	`number \| null`	— _ `types/restTool.ts:61`_
`createdAt`	`string`	— _ `types/restTool.ts:62`_
`updatedAt`	`string`	— _ `types/restTool.ts:63`_

`RestToolMethod`

Source: types/restTool.ts:1

Kind 2097152

`RestToolAuthType`

Source: types/restTool.ts:2

Kind 2097152

`RestToolBodyMode`

Source: types/restTool.ts:3

Kind 2097152

`RestToolParamIn`

Source: types/restTool.ts:4

Kind 2097152

`RestToolParamType`

Source: types/restTool.ts:5

Kind 2097152

`RestToolParamRow`

One query-string or header entry. valueTemplate may contain {{token}}.

Source: types/restTool.ts:8

Interface

Field	Type	Description
`key`	`string`	— _ `types/restTool.ts:9`_
`valueTemplate?`	`string`	— _ `types/restTool.ts:10`_
`description?`	`string`	— _ `types/restTool.ts:11`_
`required?`	`boolean`	— _ `types/restTool.ts:13`_

`RestToolParamDescriptor`

Declares one agent-fillable {{token}} referenced in url/params/headers/body.

Source: types/restTool.ts:17

Interface

Field	Type	Description
`name`	`string`	— _ `types/restTool.ts:18`_
`in?`	`RestToolParamIn`	— _ `types/restTool.ts:20`_
`type?`	`RestToolParamType`	— _ `types/restTool.ts:22`_
`description?`	`string`	— _ `types/restTool.ts:23`_
`required?`	`boolean`	— _ `types/restTool.ts:25`_

`RestToolResponseMapping`

Reshapes the raw JSON response before the agent sees it, e.g. `{ field: 'name', path: '@data.user.name' }'.

Source: types/restTool.ts:29

Interface

Field	Type	Description
`field`	`string`	— _ `types/restTool.ts:30`_
`path`	`string`	Must look like `"@data.field.path"`. — _ `types/restTool.ts:32`_

`CreateRestToolInput`

Source: types/restTool.ts:66

Interface

Field	Type	Description
`name`	`string`	— _ `types/restTool.ts:67`_
`description?`	`string`	— _ `types/restTool.ts:68`_
`method`	`RestToolMethod`	— _ `types/restTool.ts:69`_
`url`	`string`	— _ `types/restTool.ts:70`_
`queryParams?`	`RestToolParamRow[]`	— _ `types/restTool.ts:71`_
`headers?`	`RestToolParamRow[]`	— _ `types/restTool.ts:72`_
`bodyMode?`	`RestToolBodyMode`	— _ `types/restTool.ts:74`_
`bodyTemplate?`	`string`	— _ `types/restTool.ts:75`_
`paramDescriptors?`	`RestToolParamDescriptor[]`	— _ `types/restTool.ts:76`_
`authType?`	`RestToolAuthType`	— _ `types/restTool.ts:78`_
`secretRef?`	`string`	Required when `authType: 'bearerSecret'` — a `ProjectSecret` id. — _ `types/restTool.ts:80`_
`responseMappings?`	`RestToolResponseMapping[]`	— _ `types/restTool.ts:81`_
`isEnabled?`	`boolean`	— _ `types/restTool.ts:83`_

`UpdateRestToolInput`

All fields optional — only what you pass is changed.

Source: types/restTool.ts:87

Kind 2097152

`DiscoverRestToolsParams`

Source: types/restTool.ts:92

Interface

Field	Type	Description
`page?`	`number`	— _ `types/restTool.ts:94`_
`limit?`	`number`	— _ `types/restTool.ts:96`_
`search?`	`string`	Free-text match against `name`/`description`. — _ `types/restTool.ts:98`_
`scope?`	`"mine"`	Restricts to the asserted external user's own tools (`ProjectRuntimeContext` only). — _ `types/restTool.ts:100`_

`RestToolTestResult`

Source: types/restTool.ts:103

Interface

Field	Type	Description
`status`	`number`	— _ `types/restTool.ts:104`_
`ok`	`boolean`	— _ `types/restTool.ts:105`_
`body`	`unknown`	Raw JSON (or text) response body. — _ `types/restTool.ts:107`_
`mapped`	`unknown`	`body` reshaped by `responseMappings` — identical to what the agent receives. — _ `types/restTool.ts:109`_

`TestRestToolInput`

testValues stand in for agent-fillable args (and externalUserId if referenced) — never persisted, never usable by an agent.

Source: types/restTool.ts:113

Interface

Field	Type	Description
`toolId?`	`string`	— _ `types/restTool.ts:114`_
`draft?`	`Partial<CreateRestToolInput>`	— _ `types/restTool.ts:115`_
`testValues?`	`Record<string, string>`	— _ `types/restTool.ts:116`_
`

providers — @personaai/sdk

skills — @personaai/sdk