Flow Deployment

Tables

There are two tables you need to know about: flow_deployments and flow_deployment_tags.

flow_deployments

flow_deployments table

Read-only columns: we don't enforce column-level permissions at the moment, updating these column will cause problems.

• id: ID of the deployment, we use UUIDv7, therefore we can sort deployments by ID and the result will be ordered by creation time.

• created_at

• user_id: owner of the deployment.

• entrypoint: Flow ID, the main flow of this deployment, when starting the deployment, this flow will be called.

Customizable columns: update these columns to change the behavior of the deployment

• start_permission: specify who can call this deployment, this column replace is_public, start_shared, start_unverified columns of flows table. Possible values:

  • "Owner": only owner of the deployment.

  • "Authenticated": any authenticated user.

  • "Anonymous": unauthenticated user (start_flow_unverified).

  Default value will be inferred from flow config.

• output_instructions: (true/false) if set to true, will stop flow and return the transaction when available. Default is false.

• action_identity: (public key) When set, will append an Action Identity memo to instructions. Deployment owner must also have a hard-coded wallet with this public key. Default: null.

• fees: specify address and amount to send fee to. Default: empty list. Example:

[
 ["2cruTfCER3HaFwXnR99uM3jM1nPAPR5eWmVF2PiM7viR", 10000],
 ["9tmSkymh34zo33DJYcKxhHBHMhdLyWNMPtvgA1cz1occ", 10000]
]

• solana_network: Solana cluster and RPC URL. Default: same as flow config. Example:

{
  "url": "https://api.devnet.solana.com",
  "cluster": "devnet"
}

flow_deployments_tags

Tags allow calling flow deployments in a human-friendly way.

A "latest" tag will be created automatically and point to the latest deployment of a flow.

API Authentication

All examples will need authentication headers, using one of the methods below. I will omit them for brevity.

Using access token:

-H "Authorization: Bearer $ACCESS_TOKEN"

Using API key:

-H "x-api-key: $API_KEY"

Unauthenticated user, using public key (like in start_flow_unverified):

-H "Authorization: Bearer $PUBLIC_KEY"

Deploy a flow

Request:

curl -X POST https://dev-api.spaceoperator.com/flow/deploy/$FLOW_ID

Only owner of flow can deploy.

Response:

{"deployment_id":"0194e5ac-9103-7c52-971e-f71f83c5de2e"}

Inserted row in flow_deployments table:

{
  "id": "0194e5ac-9103-7c52-971e-f71f83c5de2e",
  "created_at": "2025-02-08 13:07:59.35528",
  "user_id": "885623c5-d001-41da-9d34-5577e49df350",
  "entrypoint": 3675,
  "start_permission": "Owner",
  "output_instructions": false,
  "action_identity": null,
  "fees": [],
  "solana_network": {
    "url": "https://api.devnet.solana.com",
    "cluster": "devnet"
  }
}

Inserted row in flow_deployments_tags table:

{
  "user_id": "885623c5-d001-41da-9d34-5577e49df350",
  "entrypoint": 3675,
  "tag": "latest",
  "deployment_id": "0194e5ac-9103-7c52-971e-f71f83c5de2e",
  "description": null
}

Call a deployment

We unify /start, /start_shared, /start_unverified into only one /deployment/start route. It depends on which user is calling:

• If it is the owner, behavior is same as /start

• If it is another user, behavior is same as /start_shared

• If it is an unauthenticated user, /start_unverified

Column start_permission will decide which users can call the deployment. Note: if the wrong user is calling, it will return a "404 not found" error instead of a permission error.

You can specify deployment either by ID or by flow ID and tag.

Call via ID:

curl -X POST https://dev-api.spaceoperator.com/deployment/start?id=$ID

Call via flow ID and tag:

curl -X POST https://dev-api.spaceoperator.com/deployment/start?flow=$FLOW_ID&tag=$TAG

If you don't specify tag, default "latest" tag will be used:

curl -X POST https://dev-api.spaceoperator.com/deployment/start?flow=$FLOW_ID

JSON request body:

export interface StartDeploymentParams {
  inputs?: Record<string, IValue>;
  action_signer?: string;
}

Example body:

{
  "inputs": {
    "sender": {
      "S": "5B1yr3JTyijfCfrsvHTgSkVEQWNMCE7w6f1WQkuBzAfK"
    },
    "amount": {
      "D": "3.14"
    }
  },
  "action_signer": "5B1yr3JTyijfCfrsvHTgSkVEQWNMCE7w6f1WQkuBzAfK"
}

Response: same as start flow response

{
  "flow_run_id": "5ede3d1a-67ae-452a-95ee-189d76377dd5",
  "token": "fr-Xt49GmeuRSqV7hiddjd91Q323_SUWZ5ViPUJXoNHh9yJ_Tf60y0bG6p1bfthzPtR"
}

You can query flow_run of a deployment using the new flow_run.deployment_id column:

supabase
    .from("flow_run")
    .select("*")
    .eq("deployment_id", id);

Normal flow_run will have deployment_id set to null.