Custom API

Overview

The Custom API integration lets you connect any REST API — internal microservices, third-party APIs not natively supported by Rapidfolio, or legacy systems — by providing an OpenAPI (Swagger) specification. Rapidfolio parses the spec and auto-generates callable actions for every endpoint defined in it.

This is the recommended approach for internal APIs, staging environments, or any service you want to invoke from a procedure without building a native integration.

---

Setup

1. Go to Dashboard → Connections and click New Connection.
2. Select Custom API.
3. Provide your OpenAPI specification in one of two ways:
   • URL: Enter a URL that serves the OpenAPI JSON or YAML (e.g., https://api.yourcompany.com/openapi.json). Rapidfolio fetches the spec when the connection is created.
   • Paste: Paste the OpenAPI JSON or YAML directly into the spec editor.
4. Configure authentication (see below).
5. Set the Base URL — the root URL that all API paths will be resolved against (e.g., https://api.yourcompany.com/v1). If defined in the spec's servers field, this is pre-populated.
6. Name the connection and select the environment.
7. Click Save.

Rapidfolio validates the spec on save. If parsing fails, you will see inline errors indicating which parts of the spec are invalid.

Authentication

Custom API connections support the following authentication methods:

Method	Description
API Key (Header)	Adds a custom header (e.g., X-API-Key: your-key) to every request
API Key (Query)	Appends a query parameter (e.g., ?apiKey=your-key) to every request
Bearer Token	Adds Authorization: Bearer <token> to every request
Basic Auth	Adds Authorization: Basic <base64(user:password)> to every request
None	No authentication — for internal APIs accessible without credentials

---

Generated Actions

Once your spec is saved, Rapidfolio generates one action per OpenAPI operation (operationId). Each action appears as a callable tool in the Tool Call node inspector.

Actions are named after the operationId defined in your spec. If no operationId is set, Rapidfolio generates a name from the HTTP method and path (e.g., post_payments, get_customers_id).

Example spec snippet:

paths:
  /customers/{customerId}:
    get:
      operationId: getCustomer
      summary: Retrieve a customer
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string

This generates a getCustomer action with a required customerId parameter.

Parameter Mapping

Rapidfolio maps action parameters from all OpenAPI parameter locations:

OpenAPI location	Behaviour
path	Interpolated into the URL path
query	Appended as query string parameters
header	Added as request headers
body (requestBody)	Sent as the JSON request body

Parameter types, formats, and required flags from the spec are respected and surfaced in the procedure editor.

---

Human Review

Custom API actions do not require human review by default. If you want to gate a specific action behind a review step, add a Human Review node before the Tool Call node in your procedure graph.

For actions that modify data or trigger financial operations in your internal systems, we recommend always placing a Human Review node upstream.

---

Example: Internal Risk API

Suppose your team has an internal risk scoring service at https://risk.internal.yourcompany.com/api/v1 with the following spec:

openapi: "3.0.0"
info:
  title: Risk Scoring API
  version: "1.0"
servers:
  - url: https://risk.internal.yourcompany.com/api/v1
paths:
  /score:
    post:
      operationId: scoreApplication
      summary: Score a loan application
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                applicantId:
                  type: string
                loanAmount:
                  type: number
              required: [applicantId, loanAmount]
      responses:
        "200":
          description: Risk score result

After saving this as a Custom API connection, your procedures will have a scoreApplication action available that accepts applicantId and loanAmount.

---

Notes

• The spec must be valid OpenAPI 3.0 or 2.0 (Swagger). Rapidfolio does not currently support AsyncAPI or GraphQL schemas.
• If your internal API is not publicly accessible from Rapidfolio's servers, use a Private Connection instead.
• Specs can be updated at any time by editing the connection. Existing Tool Call nodes that reference deprecated or renamed operations will show a warning in the procedure editor.
• Rapidfolio does not follow $ref links to external URLs within a spec — inline all schemas or use a single-file spec.