Skip to content

Custom tools

List custom tools

List code-backed custom tools in the workspace with cursor pagination. Each entry includes its declaration and implementation. Requires workspace read access. OAuth scope: `api:read`.

GET/api/v2/custom-tools

List code-backed custom tools in the workspace with cursor pagination. Each entry includes its declaration and implementation. Requires workspace read access.

OAuth scope: api:read.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:read

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:read.

Query parameters

workspaceIdstringRequired

Workspace that owns the custom tool.

minLength
1
maxLength
128
searchstring

Case-insensitive substring match against the tool title.

minLength
1
maxLength
200
sortBystring

Field used to sort the result.

default
createdAt
enum
["title","createdAt","updatedAt"]
sortOrderstring

Sort direction.

default
desc
enum
["asc","desc"]
limitinteger

Maximum custom tools to return per page. Must be a whole number from 1 to 100. Defaults to 50.

default
50
minimum
1
maximum
100
cursorstring

Opaque cursor from the previous page. Send it back with the same sort and filters; only limit may change. Change anything else and pagination must restart without a cursor.

minLength
1

Responses

200

Custom tools defined in the workspace.

object

Custom tools defined in the workspace.

2 fields
dataarrayRequired

Items in the current page.

Schema details
Array itemobject

A workspace custom tool and its callable function declaration.

6 fields
idstringRequired

Unique custom tool identifier.

titlestringRequired

Display title, unique within the workspace.

schemaobjectRequired

OpenAI-style function declaration describing the callable tool surface.

2 fields
typestringRequired

Function declaration discriminator.

const
function
functionobjectRequired

OpenAI-style function definition.

3 fields
namestringRequired

Function name presented to the model.

minLength
1
descriptionstring

Optional explanation of what the function does.

parametersobjectRequired

JSON Schema describing the arguments accepted by the tool.

3 fields
typestringRequired

JSON Schema type for the arguments, usually object.

propertiesobjectRequired

Caller-defined argument schemas keyed by argument name.

Schema details
Additional propertiesvalue

Caller-defined JSON Schema for one tool argument.

requiredarray

Names of required arguments.

Schema details
Array itemstring
Additional propertiesvalue

Caller-defined extension value preserved by the public API.

Additional propertiesvalue

Caller-defined extension value preserved by the public API.

Additional propertiesvalue

Caller-defined extension value preserved by the public API.

codestringRequired

Tool implementation executed in the sandboxed function runtime.

createdAtstringRequired

ISO 8601 timestamp when the tool was created.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAtstringRequired

ISO 8601 timestamp when the tool was last updated.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Additional properties are not allowed.

nextCursorvalueRequired

Opaque cursor for the next page. Send it back as cursor; null means there are no more pages. Do not construct a cursor yourself.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Response example 1

json
{
  "data": [
    {
      "id": "V1StGXR8Z5jdHi6BmyT",
      "title": "lookup_order",
      "schema": {
        "type": "function",
        "function": {
          "name": "lookup_order",
          "description": "Look up an order by id",
          "parameters": {
            "type": "object",
            "properties": {
              "orderId": {
                "type": "string"
              }
            },
            "required": [
              "orderId"
            ]
          }
        }
      },
      "code": "return { ok: true }",
      "createdAt": "2026-06-01T09:14:00.000Z",
      "updatedAt": "2026-06-20T14:02:11.000Z"
    }
  ],
  "nextCursor": null
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit