> ## Documentation Index
> Fetch the complete documentation index at: https://darwin.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Onboard for action
> Start the exact provider-account creation step and open its first-party signup link.
This operation is a planned preview and is not callable in production yet.
The request starts only the current onboarding interaction. Darwin returns an Action with a first-party `webLink`; the provider confirms account creation before the Action can continue. Do not send profile fields, passwords, codes, or a claimed signup result in the request.
Manage the credential that will call Act when this preview becomes available.
## OpenAPI
````yaml openapi-v2.json POST /actions/{actionId}/onboard
openapi: 3.1.0
info:
title: Darwin API
version: 2.0.0
description: >-
Search executable capabilities, manage durable work through explicit Action
operations, and administer developer credentials for the signed-in account.
Operations marked planned-preview are contract scaffolding and are not
callable in production.
servers:
- url: https://api.darwin.so/api/v2
security:
- apiKey: []
- bearer: []
paths:
/actions/{actionId}/onboard:
post:
summary: Onboard for action
description: >-
Planned preview; not callable in production. Start the exact
provider-account creation step and return a first-party webLink. Account
creation is confirmed by the provider, never asserted by this request.
operationId: onboard_action
parameters:
- name: actionId
in: path
required: true
description: The Action identifier returned by Start action or List actions.
schema:
type: string
minLength: 1
maxLength: 200
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ActOnboardRequest'
responses:
'200':
description: The current truthful state of the action.
content:
application/json:
schema:
$ref: '#/components/schemas/ActOnboardActionResponse'
example:
type: onboard
actionId: action_01J9Y8M4Z7B9R6K2X3C5V1N0PQ
status: onboarding_required
result: {}
actionRequired: Complete provider onboarding in Darwin.
availableActions:
- status
- onboard
- stop
interaction:
id: interaction_01J9Y8R5Y6W7K8M9N0P1Q2R3ST
kind: onboarding
state: pending
displayName: Example Provider
hostname: example.com
revision: 2
expiresAt: '2026-09-22T22:00:00.000Z'
webLink: >-
https://darwin.so/actions/action_01J9Y8M4Z7B9R6K2X3C5V1N0PQ/onboard
example:
type: onboard
actionId: action_01J9Y8M4Z7B9R6K2X3C5V1N0PQ
status: onboarding_required
result: {}
actionRequired: Complete provider onboarding in Darwin.
availableActions:
- status
- onboard
- stop
interaction:
id: interaction_01J9Y8R5Y6W7K8M9N0P1Q2R3ST
kind: onboarding
state: pending
displayName: Example Provider
hostname: example.com
revision: 2
expiresAt: '2026-09-22T22:00:00.000Z'
webLink: >-
https://darwin.so/actions/action_01J9Y8M4Z7B9R6K2X3C5V1N0PQ/onboard
'400':
description: The request failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: The request failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: The request failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: The request failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: The request failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: The request failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
ActOnboardRequest:
title: Onboard for action (planned preview)
description: >-
Start only the current, server-bound provider signup interaction.
Personal details, passwords, one-time codes, and acceptance of provider
terms belong in the hosted flow, not this request.
type: object
additionalProperties: false
required:
- interactionId
- expectedRevision
- requestId
properties:
interactionId:
type: string
minLength: 1
maxLength: 200
expectedRevision:
type: integer
minimum: 1
requestId:
type: string
minLength: 1
maxLength: 160
pattern: ^[a-zA-Z0-9][a-zA-Z0-9._:-]*$
ActOnboardActionResponse:
title: Onboarding action (planned preview)
allOf:
- $ref: '#/components/schemas/ActActionResponse'
- type: object
required:
- type
- interaction
- webLink
properties:
type:
type: string
const: onboard
interaction:
$ref: '#/components/schemas/OnboardingInteraction'
webLink:
type: string
format: uri
Error:
type: object
additionalProperties: true
properties:
error:
type: string
message:
type: string
fields:
type: array
items:
type: object
additionalProperties: true
ActActionResponse:
title: Action
type: object
additionalProperties: false
required:
- type
- actionId
- status
- result
- actionRequired
- availableActions
properties:
type:
type: string
enum:
- start
- status
- update
- approve
- stop
- onboard
- pay
- connect
actionId:
type: string
status:
type: string
enum:
- completed
- running
- awaiting_user
- approval_required
- onboarding_required
- connection_required
- payment_required
- insufficient_authority
- provider_unavailable
- stopped
result:
type: object
additionalProperties: true
actionRequired:
type:
- string
- 'null'
availableActions:
type: array
items:
type: string
enum:
- status
- update
- approve
- onboard
- pay
- connect
- stop
interaction:
oneOf:
- $ref: '#/components/schemas/OnboardingInteraction'
title: Onboarding
- $ref: '#/components/schemas/ConnectionInteraction'
title: Connection
- $ref: '#/components/schemas/PaymentInteraction'
title: Payment
discriminator:
propertyName: kind
feedbackRequest:
type: object
additionalProperties: false
required:
- interactionId
- state
- role
- revision
properties:
interactionId:
type: string
minLength: 1
maxLength: 200
state:
type: string
enum:
- OPEN
- SUBMITTED
- EXPIRED
- UNAVAILABLE
role:
type: string
enum:
- REQUESTER
- FULFILLER
closesAt:
type: string
format: date-time
revision:
type: integer
minimum: 1
webLink:
type: string
format: uri
policyState:
type: object
additionalProperties: false
required:
- state
- code
- scope
properties:
state:
type: string
enum:
- REVIEW_REQUIRED
- RESTRICTED
- BLOCKED
code:
type: string
enum:
- safety_review_required
- authorization_restricted
- action_blocked
scope:
type: string
enum:
- ACTION
- CAPABILITY
- LISTING
- AI
- ACCOUNT
expiresAt:
type: string
format: date-time
webLink:
type: string
format: uri
webLink:
type: string
format: uri
OnboardingInteraction:
title: Onboarding
description: >-
The exact provider-account creation step bound to the Action. The
provider, account type, required fields, and terms are reviewed in the
first-party browser flow.
type: object
additionalProperties: false
required:
- id
- kind
- state
- displayName
- hostname
- revision
- expiresAt
properties:
id:
type: string
minLength: 1
maxLength: 200
kind:
type: string
const: onboarding
state:
type: string
enum:
- required
- pending
- complete
- declined
- expired
- failed
displayName:
type: string
minLength: 1
maxLength: 200
hostname:
type: string
minLength: 1
maxLength: 253
revision:
type: integer
minimum: 1
expiresAt:
type: string
format: date-time
ConnectionInteraction:
title: Connection
type: object
additionalProperties: false
required:
- id
- kind
- state
- displayName
- hostname
- expiresAt
- retentionChoices
- scopeDescriptions
properties:
id:
type: string
minLength: 1
maxLength: 200
kind:
type: string
const: connection
state:
type: string
enum:
- required
- pending
- complete
- declined
- expired
- failed
displayName:
type: string
minLength: 1
maxLength: 200
hostname:
type: string
minLength: 1
maxLength: 253
expiresAt:
type: string
format: date-time
retentionChoices:
type: array
maxItems: 2
items:
type: string
enum:
- temporary
- saved
scopeDescriptions:
type: array
maxItems: 12
items:
type: string
PaymentInteraction:
title: Payment
type: object
additionalProperties: false
required:
- id
- kind
- state
- displayName
- hostname
- expiresAt
- payment
properties:
id:
type: string
minLength: 1
maxLength: 200
kind:
type: string
const: payment
state:
type: string
enum:
- required
- pending
- complete
- declined
- expired
- failed
displayName:
type: string
minLength: 1
maxLength: 200
hostname:
type: string
minLength: 1
maxLength: 253
expiresAt:
type: string
format: date-time
payment:
type: object
additionalProperties: false
required:
- amountMinor
- currency
- items
- feesMinor
- protocol
- checkoutRevision
- checkoutDigest
properties:
amountMinor:
type: integer
minimum: 0
currency:
type: string
pattern: ^[A-Z]{3}$
items:
type: array
maxItems: 100
items:
type: object
additionalProperties: false
required:
- id
- label
- quantity
- amountMinor
properties:
id:
type: string
minLength: 1
maxLength: 200
label:
type: string
minLength: 1
maxLength: 240
quantity:
type: integer
minimum: 1
amountMinor:
type: integer
minimum: 0
feesMinor:
type: integer
minimum: 0
protocol:
type: string
enum:
- DARWIN_WALLET
- HOSTED_CHECKOUT
- UCP_SPT
- ACP_SPT
- MPP_SPT
- X402
checkoutRevision:
type: string
minLength: 1
maxLength: 200
checkoutDigest:
type: string
pattern: ^sha256:[a-f0-9]{64}$
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
x-fern-header:
name: apiKey
env: DARWIN_API_KEY
description: >-
Pass your Darwin API key in the x-api-key header. You can also
authenticate with Authorization: Bearer .
bearer:
type: http
scheme: bearer
bearerFormat: Darwin API key or OAuth access token
x-fern-bearer:
name: token
env: DARWIN_API_KEY
description: >-
Pass a Darwin API key or OAuth access token as Authorization: Bearer
. You can also pass a Darwin API key in x-api-key.
````