Zion.app Headless BaaS Skill#

Overview#

This skill outlines how to build frontend applications utilizing Zion.app as a headless Backend-as-a-Service (BaaS). Zion exposes all backend interactions (database, actionflows, third-party APIs, and AI agents) through a single, unified GraphQL API.

• HTTP URL: https://zion-app.functorz.com/zero/{projectExId}/api/graphql-v2
• WebSocket URL: wss://zion-app.functorz.com/zero/{projectExId}/api/graphql-subscription

Token Acquisition & Authentication (CRITICAL)#

To interact with authenticated endpoints, you must obtain a JWT token by logging in or registering. Unauthenticated requests are assigned an anonymous user role. The JWT can be obtained in two ways. One is via username + password login. The other one is by querying the Meta API & fetching runtime backend token. The token return in FETCH_DATA_VISUALIZER is the runtime backend token.

1. Username Registration & Login#

You should ask user for username and password.

graphql

mutation AuthenticateWithUsername($username: String!, $password: String!, $register: Boolean!) {
  authenticateWithUsername(username: $username, password: $password, register: $register) {
    account { id, permissionRoles }
    jwt { token }
  }
}

Note: Both mutations return FZ_Account which is a subset of the full account type. It contains only email, id, permissionRoles, phoneNumber, profileImageUrl, roles, and username.

Developer Authentication with Zion.app (Meta API)#

If you need to interact directly with the Zion platform (Meta API) to fetch project schemas, list projects, or authenticate as an admin to the runtime backend, follow these steps:

1. Acquire Developer JWT Token#

There are two ways to acquire a developer token: via OAuth Flow or via Email/Password login.

Option A: OAuth Flow

Set up a local HTTP server to receive the OAuth callback. Open the Zion authentication endpoint ( https://auth.functorz.com/login) in the browser and wait for the token parameter.

You can run the bundled authentication script:

bash

cd ~/.openclaw/skills/zion_baas/scripts
npm run auth

Option B: Email/Password Login

You can directly login with an email and password using the Meta API:

bash

cd ~/.openclaw/skills/zion_baas/scripts
npm run auth:email <email> <password>

2. Querying the Meta API & Fetching Runtime Backend Token#

Use the developer JWT token as a Bearer token against the Meta API ( https://zionbackend.functorz.com/api/graphql) to get the schema or data visualizer tokens. The data visualizer token grants administrative access to the project's runtime backend ( zeroUrl).

You can run the bundled script to fetch the token. It requires the developer token to be present in .zion/credentials.yaml.

bash

cd ~/.openclaw/skills/zion_baas/scripts
npm run fetch-token -- <projectExId>

You can also search for projects or fetch their schema via the Meta API using the bundled meta script:

bash

cd ~/.openclaw/skills/zion_baas/scripts
# Search projects (returns project names and exIds)
npm run meta -- search-projects "optional search term"

# Fetch project schema (returns data models, actionflows, apis)
npm run meta -- fetch-schema <projectExId>

Credential Management & State Persistence#

All credentials and project state MUST be persisted in the .zion directory at the root of the user's project in YAML format, typically in a file named .zion/credentials.yaml.

Required YAML Format#

The credentials file must adhere to the following structure:

yaml

# .zion/credentials.yaml
developer_token:
  token: "<your_developer_jwt_token>" # Used to communicate with zionbackend.functorz.com
  expiry: "<timestamp_or_date_of_expiry>"

project:
  exId: "<project_ex_id>"
  name: "<project_name>"
  admin_token:
    token: "<runtime_backend_admin_token>"
    expiry: "<timestamp_or_date_of_expiry>"
  other_users:
    - user_id: "<user_id>"
      user_tags:
        - "<notable_information_about_the_user_1>"
      token:
        token: "<user_jwt_token>"
        expiry: "<timestamp_or_date_of_expiry>"

• developer_token: The JWT token acquired via the OAuth flow, used against the Meta API ( zionbackend.functorz.com).
• project: Contains the core project identifiers ( exId, name), the admin_token (data visualizer token) for the runtime backend, and other_users.
• other_users: A list of authenticated users (e.g., test accounts) containing their user_id, helpful user_tags to identify their purpose, and their token.
• expiry: All stored tokens must include an associated expiry.

Executing GraphQL Queries & Subscriptions via CLI#

You can use the bundled scripts to quickly test GraphQL queries, mutations, and subscriptions from the command line without writing frontend boilerplate. These scripts automatically read the correct token from your project's .zion/credentials.yaml.

1. Execute a Query or Mutation#

Pass your GraphQL query or mutation as a string.

bash

cd ~/.openclaw/skills/zion_baas/scripts
npm run gql -- <projectExId> <role> '<query_string>' '<optional_variables_json>'

• <role>: Can be admin (uses data visualizer token), anonymous (no token), or a specific user_id (fetches token from other_users in .zion/credentials.yaml).

Example:

bash

npm run gql -- myProjectEx123 admin 'query GetProject($id: Int!) { project(id: $id) { name } }' '{"id": 1}'

2. Listen to a Subscription#

Pass your GraphQL subscription as a string.

bash

cd ~/.openclaw/skills/zion_baas/scripts
npm run subscribe -- <projectExId> <role> '<query_string>' '<optional_variables_json>'

The script will establish a WebSocket connection and continuously print events as they arrive until you kill it (Ctrl+C).

Database & GraphQL Schema Rules#

• Use zion MCP server or webfetch/curl to introspect the schema before making assumptions.

The GraphQL schema is automatically generated directly from the PostgreSQL data model.

CRITICAL CATCH-ALL RULE: If you are ever in doubt about the exact structure, available fields, Enum values (like [Enum:ROUNDING_MODE]), or specific arguments for an endpoint, you must use the webfetch/curl tool to introspect the live GraphQL schema via the provided endpoint URL before making assumptions.

1. Naming Conventions & Root Operations#

Each table generates corresponding root query, mutation, and subscription fields. For a table named [table]:

Queries

• [table]: Fetch lists (supports where, order_by, distinct_on, limit, offset).
• [table]_by_pk: Fetch single record by primary key ( id).
• [table]_aggregate: Aggregate queries ( count, sum, avg, min, max).
• [table]_group_by: Group records based on specified fields.
• fz_[table]_by_[column]: Auto-generated spatial proximity search if the table contains a geo_point column.
• Relay API: If configured, generates a cursor-based pagination query returning a Connection_[table] object.

Mutations

• insert_[table], insert_[table]_one: Create records. Supports nested inserts and on_conflict (requires constraint and update_columns).
• update_[table], update_[table]_by_pk: Modify records. Uses _set (replace) and _inc (increment numeric). where is required ( !) for bulk updates. (Note: Hasura JSONB update operators like _append/ _delete_key are not supported).
• delete_[table], delete_[table]_by_pk: Remove records. where is required ( !) for bulk deletes.
• export_[table]: Trigger a data export task for the table.

Subscriptions

• [table], [table]_by_pk, [table]_aggregate: Live queries mirroring their standard query counterparts.

2. Column Types and Data Mappings#

Primitive Types

• text → String, integer → Int, bigint, bigserial → bigint, float8 → Float8, decimal → Decimal, boolean → Boolean, jsonb → jsonb.
• Time/Date: timestamptz, timetz, date, interval.
• Geo: geo_point → geography.

Composite (Media) Types

Media columns ( image, file, video) are structurally 1:N relations but act as fields.

• Single Media: Stored as [column]_id (e.g., cover_image_id) referencing system asset tables ( FZ_Image, FZ_File, FZ_Video).
• Media Lists: Types like image_list, video_list, file_list map to GraphQL Arrays and are stored as [column]_ids (e.g., gallery_images_ids).

System-Managed Columns

id, created_at, updated_at are read-only and automatically managed. They cannot be used in mutation inputs ( _set, _inc, insert inputs).

3. Relationships#

Relationships are defined by foreign keys and determine GraphQL nested fields:

• 1:1 (One-to-One): Yields a single nested object (e.g., meta: post_meta).
• 1:N (One-to-Many): Yields an array (e.g., post_tags: [post_tag]) and an aggregate object (e.g., post_tags_aggregate).

4. Filtering ( where clauses)#

Filters rely on [table]_bool_exp.

Logical Operators

• _and: [bool_exp], _or: [bool_exp], _not: bool_exp

Relation Filters

Navigate relationships using the relationship field name directly. The value is a nested [related_table]_bool_exp object.

• To-One Relationships (1:1, N:1): Filters the parent record based on the single related record's fields. (e.g., Find posts where the author's name is "John": author: { name: { _eq: ... } })
• To-Many Relationships (1:N, N:M): Uses EXISTS semantics. The parent record is returned if any related record in the array matches the nested condition. (e.g., Find posts that have at least one tag named "Tech": post_tags: { tag: { name: { _eq: ... } } })

Comparison Predicates (Strict Pattern)

Zion uses a strict Operator-First Pattern. A predicate must start with the operator. If it's a generic operator, the operand wrapper type must match the final evaluated type, not necessarily the column type.

Structure:

json

{
  "_operator": {
    "operand_type": {
      "left_operand": { ... },
      "right_operand": { ... }
    }
  }
}

• Operators:
  • Comparison (Generic): _eq, _neq, _gt, _lt, _gte, _lte
  • Array (Generic): _in, _nin
  • Nullity (Generic, Unary): _is_null, _is_not_null
  • Text (String Pattern): _like, _nlike, _ilike, _nilike, _similar, _nsimilar
  • JSONB: _contains, _contained_in, _has_key, _has_keys_any, _has_keys_all
  • Boolean: _is_true, _is_false
  • Collection: _is_empty, _is_not_empty
• Operand Definitions ( left_operand / right_operand):
  • Literal: {"literal": value}
  • Column: {"column": "field_name"}
  • Function: {"function_name": { ...args }}
• Operand Types (Determined by Final Value): bigint_operand, text_operand, boolean_operand, timestamptz_operand, etc.

Example Predicate (Extract Month from Timestamp and check if = 12):

json

{
  "_eq": {
    "bigint_operand": {
      "left_operand": {
        "extract_timestamptz": { "time": { "column": "created_at" }, "unit": "MONTH" }
      },
      "right_operand": { "literal": "12" }
    }
  }
}

5. Aggregations, Window Functions, and Order By#

Aggregation ( [table]_aggregate)

Returns an aggregate query object containing two main fields:

• nodes: An array of the actual table objects ( [table!]!) containing the raw data rows that match the query's where, limit, offset, and order_by criteria.

• aggregate: An object containing statistical calculations over the matched rows:

  • count(columns: [Enum], distinct: Boolean):

    • If no columns are provided, it counts all rows ( COUNT(*)).
    • If distinct: true and 1+ columns are provided, it counts unique values or unique combinations of the specified columns.
    • If distinct: false and multiple columns are provided, the system restricts the count to only evaluate the first column in the array.

  • sum, avg: Only available for numeric columns.

  • max, min: Available for comparable columns (numeric, time, text).

Window Functions

Advanced analytical operations like ROW_NUMBER, RANK, DENSE_RANK, NTH_VALUE are supported in specific formula and window frame inputs.

Sorting ( order_by)

Supports sorting by:

1. Direct columns: { title: asc }
2. Related 1:1 records: { author: { name: desc } }
3. Aggregates of N:1 records: { post_tags_aggregate: { count: desc } }
4. Vector Search: Text columns may support similarity sorting if the TEXT_COLUMN_VECTOR_SORT extension is applied.

6. Formula Functions (Operands)#

Functions are used inside operand wrappers by wrapping the uppercase function name around its arguments (e.g., {"EXTRACT_TIMESTAMPTZ": { "time": ..., "unit": ... }}).

Input Constraints & Semantics

• [TYPE]: Indicates a required column or scalar operand of that exact type.
• [TYPE?]: Indicates an optional operand (usually defaults to 0 or null).
• [ANY]: Accepts any column or scalar operand of any type.
• [NUMERIC]: Accepts BIGINT, INTEGER, DECIMAL, FLOAT8, or BIGSERIAL.
• [COMPARABLE]: Accepts NUMERIC types, TEXT, DATE, TIMESTAMPTZ, TIMETZ, or INTERVAL.
• [ANY[]]: Accepts an array operand of any type.
• [Enum:NAME]: Requires an explicit Enum value matching the [NAME] definition (e.g., [Enum:DATE_UNIT] requires YEAR, MONTH, etc.).
• Nested Functions: Arguments can often be the output of other functions, provided the output type matches the expected input type.

Manipulation

• CONCAT(items: [TEXT[]])
• SUBSTRING(source_text: [TEXT], start_index: [BIGINT], end_index: [BIGINT])
• LEFT(source_text: [TEXT], length: [BIGINT])
• RIGHT(source_text: [TEXT], length: [BIGINT])
• LOWER(source_text: [TEXT])
• UPPER(source_text: [TEXT])
• TRIM(text: [TEXT])
• TRIM_TRAILING_ZERO(source_text: [TEXT])
• REPEAT(text: [TEXT], times: [BIGINT])
• ENCODE_URL(text: [TEXT])
• DECODE_URL(text: [TEXT])
• ARRAY_CONCAT(first_array: [ANY[]], second_array: [ANY[]])
• SLICE(array: [ANY[]], start_index: [BIGINT], length: [BIGINT])
• UNIQUE(array: [ANY[]])
• COALESCE(array: [ANY[]])

Search & Replace

• REPLACE_OCCURRENCES(source_text: [TEXT], search_text: [TEXT], replace_text: [TEXT], max_replacements: [BIGINT])
• REPLACE_AT_POSITION(source_text: [TEXT], start_index: [BIGINT], length: [BIGINT], replace_text: [TEXT])
• POSITION(source_text: [TEXT], search_text: [TEXT])
• CONTAINS(source_text: [TEXT], search_text: [TEXT])

Regex

• REGEX_EXTRACT(text: [TEXT], regex: [TEXT])
• REGEX_REPLACE(text: [TEXT], regex: [TEXT], replacement: [TEXT])
• REGEX_EXTRACT_ALL(text: [TEXT], regex: [TEXT])
• REGEX_MATCH(text: [TEXT], regex: [TEXT])

Formatting & Utils

• TEXT_DECIMAL_FORMAT(number: [DECIMAL], fraction_digits: [BIGINT], rounding_mode: [Enum:ROUNDING_MODE], clear_trailing_zeros: [BOOLEAN])
• NUMBER_FORMAT(number: [DECIMAL], fraction_digits: [BIGINT], format: [Enum:NUMBER_FORMAT])
• STRING_LEN(source_text: [TEXT])
• RANDOM_TEXT(min_length: [BIGINT], max_length: [BIGINT], include_numbers: [BOOLEAN], include_lower_case: [BOOLEAN], include_upper_case: [BOOLEAN])
• UUID()
• JOIN(array: [TEXT[]], separator: [TEXT])
• SPLIT(source_text: [TEXT], delimiter: [TEXT])
• ARRAY_LEN(array: [ANY[]])

Arithmetic

• ADD(value0: [NUMERIC], value1: [NUMERIC])
• SUBTRACT(minuend: [NUMERIC], subtrahend: [NUMERIC])
• MULTIPLY(value0: [NUMERIC], value1: [NUMERIC])
• DIVIDE(dividend: [DECIMAL], divisor: [DECIMAL])
• MODULO(dividend: [NUMERIC], divisor: [NUMERIC])
• ABS(number: [NUMERIC])
• POW(base: [NUMERIC], exponent: [NUMERIC])
• LOG(base: [DECIMAL], argument: [DECIMAL])

Rounding & Formats

• ROUND_UP(number: [DECIMAL])
• ROUND_DOWN(number: [DECIMAL])
• DECIMAL_FORMAT(number: [DECIMAL], fraction_digits: [BIGINT], rounding_mode: [Enum:ROUNDING_MODE])

Generators

• RANDOM_BIGINT(min_length: [BIGINT], max_length: [BIGINT])
• SEQUENCE(start: [BIGINT], end: [BIGINT], step: [BIGINT])

Current Time

• CURRENT_DATE()
• CURRENT_TIMETZ()
• CURRENT_TIMESTAMPTZ()

Constructors

• MAKE_DATE(years: [BIGINT], months: [BIGINT], days: [BIGINT])
• MAKE_TIMETZ(hours: [BIGINT?], minutes: [BIGINT?], seconds: [BIGINT?], milliseconds: [BIGINT?])
• MAKE_TIMESTAMPTZ(years: [BIGINT], months: [BIGINT], days: [BIGINT], hours: [BIGINT?], minutes: [BIGINT?], seconds: [BIGINT?], milliseconds: [BIGINT?])
• MAKE_INTERVAL(years: [BIGINT], months: [BIGINT], weeks: [BIGINT], days: [BIGINT], hours: [BIGINT], minutes: [BIGINT], seconds: [BIGINT], milliseconds: [BIGINT])
• FROM_DATE_AND_TIMETZ(date: [DATE], timetz: [TIMETZ])

Extraction & Formatting

• EXTRACT_DATE(time: [DATE], unit: [Enum:DATE_UNIT])
• EXTRACT_TIMETZ(time: [TIMETZ], unit: [Enum:TIME_UNIT])
• EXTRACT_TIMESTAMPTZ(time: [TIMESTAMPTZ], unit: [Enum:TIMESTAMP_UNIT])
• DATE_FORMAT(time: [DATE], format: [TEXT], language: [Enum:LANGUAGE])
• TIMETZ_FORMAT(time: [TIMETZ], format: [TEXT], language: [Enum:LANGUAGE])
• TIMESTAMPTZ_FORMAT(time: [TIMESTAMPTZ], format: [TEXT], language: [Enum:LANGUAGE])
• DURATION_FORMAT(duration: [DECIMAL], unit: [Enum:DURATION_UNIT], format: [TEXT])
• RELATIVE_DATE(time: [DATE], language: [Enum:LANGUAGE], hide_suffix: [BOOLEAN])
• RELATIVE_TIMESTAMPTZ(time: [TIMESTAMPTZ], language: [Enum:LANGUAGE], hide_suffix: [BOOLEAN])

Calculations & Deltas

• DELTA_DATE(date: [DATE], increase: [BOOLEAN], years: [BIGINT?], months: [BIGINT?], days: [BIGINT?])
• DELTA_TIMETZ(timetz: [TIMETZ], increase: [BOOLEAN], hours: [BIGINT?], minutes: [BIGINT?], seconds: [BIGINT?], milliseconds: [BIGINT?])
• DELTA_TIMESTAMPTZ(timestamptz: [TIMESTAMPTZ], increase: [BOOLEAN], years: [BIGINT?], months: [BIGINT?], days: [BIGINT?], hours: [BIGINT?], minutes: [BIGINT?], seconds: [BIGINT?], milliseconds: [BIGINT?])
• EXTRACT_DATE_DURATION(start_time: [DATE], end_time: [DATE], unit: [Enum:DATE_UNIT])
• EXTRACT_TIMETZ_DURATION(start_time: [TIMETZ], end_time: [TIMETZ], unit: [Enum:TIME_UNIT])
• EXTRACT_TIMESTAMPTZ_DURATION(start_time: [TIMESTAMPTZ], end_time: [TIMESTAMPTZ], unit: [Enum:TIMESTAMP_UNIT])

Conversions

• FROM_TIMESTAMPTZ_TO_DATE(timestamptz: [TIMESTAMPTZ])
• FROM_TIMESTAMPTZ_TO_TIMETZ(timestamptz: [TIMESTAMPTZ])

Geography

• FROM_COORDINATES(latitude: [DECIMAL], longitude: [DECIMAL])
• GEO_DISTANCE(point0: [GEO_POINT], point1: [GEO_POINT], unit: [Enum:GEO_DISTANCE_UNIT])
• GEO_LONGITUDE(geo: [GEO_POINT])
• GEO_LATITUDE(geo: [GEO_POINT])

Aggregates

• SUM(array: [NUMERIC[]])
• AVG(array: [NUMERIC[]])
• MAX(value0: [COMPARABLE], value1: [COMPARABLE])
• MIN(value0: [COMPARABLE], value1: [COMPARABLE])
• GREATEST(array: [COMPARABLE[]])
• LEAST(array: [COMPARABLE[]])

Element Access

• ITEM(array: [ANY[]], index: [BIGINT])
• FIRST_ITEM(array: [ANY[]])
• LAST_ITEM(array: [ANY[]])
• RANDOM_ITEM(array: [ANY[]])
• ARRAY_POSITION(array: [ANY[]], item: [ANY])

JSONB

• JSON_EXTRACT_BY_DOT_NOTATION_JSONPATH(json: [JSONB], path: [TEXT])

Casting

• CAST_FROM_TEXT(value: [TEXT])
• CAST_COLUMN_TO_TEXT(value: [ANY])
• CAST_ARRAY_TO_TEXT(value: [ANY[]])
• CAST_TO_BIGINT(value: [ANY])
• CAST_TO_DECIMAL(value: [ANY])

Vector Search

• EMBEDDING_VECTOR_DISTANCE(embedded_text_column: [Enum:EMBEDDING_COLUMN], text: [TEXT], distance_function: [Enum:VECTOR_DISTANCE])

System

• NULL_VALUE()

Explicit Enum Definitions

When an argument requires an [Enum:NAME], you must use one of the following exact string values:

• [Enum:DATE_UNIT]: YEAR, MONTH, DAY, WEEK
• [Enum:DURATION_UNIT]: DAY, HOUR, MINUTE, SECOND, MILLISECOND
• [Enum:EMBEDDING_COLUMN]: (Dynamically generated based on columns with TEXT_COLUMN_VECTOR_SORT extension)
• [Enum:GEO_DISTANCE_UNIT]: METER, KILOMETER, MILE
• [Enum:LANGUAGE]: EN, ZH
• [Enum:NUMBER_FORMAT]: THOUSANDS_SEPARATOR, PERCENT
• [Enum:ROUNDING_MODE]: HALF_EVEN, HALF_UP, HALF_DOWN, UP, DOWN, CEILING, FLOOR
• [Enum:TIMESTAMP_UNIT]: YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, MILLISECOND, WEEK
• [Enum:TIME_UNIT]: HOUR, MINUTE, SECOND, MILLISECOND
• [Enum:VECTOR_DISTANCE]: EUCLIDEAN, COSINE

Actionflow Protocol#

Overview#

Although zion-app.functorz.com already support direct CRUD operations that can be initiated from the frontend, many backend operations are multi-step, can be long-running and sometimes have to be asynchronous. Therefore zion-app.functorz.com also supports actionflows for these scenarios. An actionflow is a directed acyclic graph made up of actionflow nodes. These nodes represent either operations (e.g. insert into databsae, invoke another actionflow) or control flow changes (condition and loop). Actionflows also have two special nodes, input and output, where the arguments and return values of the entire actionflow are defined.

Actionflows have two modes of operation, sync or async. A synchronous actionflow is executed within a single database transaction, and therefore when an unexpected error is encountered, will rollback all database changes. Synchronous actionflows have runtime limits to avoid hogging database connection. Asynchronous actionflows run each node inside a new database transaction, so they do not have rollback mechanism, but are more suited for long running tasks, like long http calls, especially those made to LLM APIs as they can take minutes. Within actionflows, all nodes of invoking AI agents built in zion-app.functorz.com natively can only be added inside async ones.

Actionflow invocation process#

In order to invoke an actionflow, one needs to obtain its id, a list of arguments and optionally its version. They are found inside the project schema. Actionflow invocation differ based on their type.

Sync actionflows

Sync actionflows can be invoked via a regular GraphQL mutation. The results will be returned in the response of the same HTTP request. Request:

gql

mutation someOperationName ($args: Json!) {
 fz_invoke_action_flow(actionFlowId: "d3ea4f95-5d34-46e1-b940-91c4028caff5", versionId: 3, args: $args)
}

json

{
  "args": {
    "yaml": "post_link:\n  url: \"https://zion-app.functorz.com\"\n",
    "img_id": 1020000000000111
  }
}

Within this query, $args corresponds to the arguments listed in the actionflow's input node. Response:

json

{
  "data": {
    "fz_invoke_action_flow": {
      "img": {
        "id": 1020000000000090,
        "url": "https://fz-zion-static.functorz.com/202510252359/a64a7eb4793728a1977d3ea9e7b7e4e8/project/2000000000521152/import/1110000000000001/image/636.jpg"
      },
      "url": "https://zion-app.functorz.com"
    }
  }
}

Async actionflows

Async actionflows are triggered via a GraphQL mutation but the results are not returned in the response of the same HTTP request. Instead, a fz_create_action_flow_task is returned, containing the id of the corresponding task, which is then used for subscribing to the result in a separate GraphQL subscription. Mutation request:

gql

mutation mh49tgie($args: Json!) {
 fz_create_action_flow_task(actionFlowId: "2a9068c5-8ee3-4dad-b3a4-5f3a6d365a2f", versionId: 4, args: $args)
}

json

{
  "args": {
    "int": 123,
    "img_id": 1020000000000116,
    "some_text": "Dreamer",
    "datetime_with_timezone": "2025-10-23T20:13:00-07:00"
  }
}

Mutation response: { "data": { "fz_create_action_flow_task": 1150000000000148 } }

Subscription request:

gql

subscription fz_listen_action_flow_result($taskId: Long!) {
  fz_listen_action_flow_result(taskId: $taskId) {
    __typename"
    output
    status
  }
}

json

{ "taskId" : 1150000000000148 }

Subscription response:

json

{
  "data": {
    "fz_listen_action_flow_result": {
      "__typename": "ActionFlowTaskResult",
      "output": {
        "img": {
          "id": 1020000000000089,
          "url": "https://fz-zion-static.functorz.com/202510262359/3a5f04371bf68d6c94bb890879101f0a/project/2000000000521152/import/1110000000000001/image/637.jpg"
        },
        "xyz": {
          "type": "Point",
          "coordinates": [
            131,
            22
          ]
        }
      },
      "status": "COMPLETED"
    }
  }
}

There might be multiple messages sent by the GraphQL subscription before the final result (inside "output") is returned, and each may contain different status values. The status field has the following transition rules:

java

switch (status) {
  case CREATED -> Set.of(PROCESSING);
  case PROCESSING -> Set.of(COMPLETED, FAILED);
  default -> Set.of();
};

AI Agent Protocol#

Overview#

Zion.app has an integrated AI agent builder, which supports multi-modal (text, video, image) inputs and outputs, prompt templating, context fetching (via database and third-party APIs), tool use (actionflows, third-party APIs and other AI agents) and structured output (JSON according corresponding JSONSchema).

AI Agents' results are delivered differently by the GraphQL service depending on the configuration of its output, namely, whether it is streaming and whether it is structured. A structured output can not be streamed but plain text can be either streamed or not. A structured output must be accompanied by a JSONSchema that describes the JSON's type.

In order to invoke an AI agent, the id and the input arguments must be obtained from the project schema. An AI agent built in Zion.app's agent builder can only be invoked via the GraphQL API asynchronously.

Invocation process for streaming output#

An example AI Agent configuration whose output is a streaming plain text will be used to illustrate this process. Its configuration is:

json

{
    "id": "mgzzu8jp",
    "summary": "An example summary of what the agent does",
    "inputs": {
      "mgzzufo2": {
        "type": "VIDEO",
        "displayName": "the_video",
      },
      "mh4cjjcf": {
        "type": "TEXT",
        "displayName": "text",
      },
      "mh4cjkyv": {
        "type": "BIGINT",
        "displayName": "some_int",
      },
      "mh4cjoof": {
        "type": "array",
        "itemType": "IMAGE",
        "displayName": "images",
      }
    },
    "output": "Unstructured Text"
}

1. A mutation is sent to start the AI agent, supplying the arguments as inputArgs and the id as zAIConfigId. The response value only contains the id of the corresponding conversation. The keys of inputArgs should be the same keys in the inputs object from the schema. Input parameters of Image / video or other binary assets types, or arrays of such types are handled slightly differently. Their key names wihtin the inputArgs object have _id suffix. e.g. the following configuration

json

{
  "inputs": {
    "mgzzufo2": {
      "type": "VIDEO",
      "displayName": "the_video",
    }
  }
}

Corresponds to:

json

{
  "inputArgs": {
    "mgzzufo2_id": 1030000000000002,
  }
}

text

Mutation request:
Query:
```gql
mutation ZAICreateConversation($inputArgs: Map_String_ObjectScalar!, $zaiConfigId: String!) {
 fz_zai_create_conversation(inputArgs: $inputArgs, zaiConfigId: $zaiConfigId)
}
```
Variables:
```json
{
  "inputArgs": {
    "mgzzufo2_id": 1030000000000002,
    "mh4cjjcf": "Just some text",
    "mh4cjkyv": 23,
    "mh4cjoof_id": [
      1020000000000097,
      1020000000000111,
      1020000000000120
    ]
  },
  "zaiConfigId": "mgzzu8jp"
}
```
Mutation response:
```json
{
  "data": {
    "fz_zai_create_conversation": 1480
  }
}
```

2. Using the obtained conversation id to subscribe to the result of the previous invocation of the AI Agent. Multiple messages may be received. The messages' status may transition from IN_PROGRESS to STREAMING to eventually COMPLETED. The last message always gives you COMPLETED status and its data field will contain the consolidated output from all the previous STEAMING messages' data field. For models that have reasoning content output, it works similarly as the actual output. i.e. Partial reasoning content will be emitted first in multiple messages in the reasoningContent field, and then when everything is ready, the entirety of reasoningContent will be emitted again the COMPLETED message. Subscription request:

Query: gql subscription ZaiListenConversationResult($conversationId: Long!) { fz_zai_listen_conversation_result(conversationId: $conversationId) { conversationId status reasoningContent images { id __typename } data __typename } } Variables: json { "conversationId": 1480 } Subscription response messages: json { "data": { "fz_zai_listen_conversation_result": { "__typename": "ConversationResult", "conversationId": 1480, "data": null, "images": null, "reasoningContent": null, "status": "IN_PROGRESS" } } } json { "data":{ "fz_zai_listen_conversation_result": { "__typename": "ConversationResult", "conversationId": 1480, "data": "This collection features three images and a short video. Two photos show the famous Chinese comedian and actor, Zhao Benshan. A third", "images": null, "reasoningContent": null, "status": "STREAMING" } } } json { "data":{ "fz_zai_listen_conversation_result": { "__typename": "ConversationResult", "conversationId": 1480, "data": " image is an anime illustration of a young woman in a \"SHOHOKU\" basketball jersey, resembling the character Haruko Akagi from the series *Slam Dunk*.", "images": null, "reasoningContent": null, "status": "STREAMING" } } } json { "data":{ "fz_zai_listen_conversation_result": { "__typename": "ConversationResult", "conversationId": 1480, "data": "This collection features three images and a short video. Two photos show the famous Chinese comedian and actor, Zhao Benshan. A third image is an anime illustration of a young woman in a \"SHOHOKU\" basketball jersey, resembling the character Haruko Akagi from the series *Slam Dunk*.", "images": null, "reasoningContent": null, "status": "COMPLETED" } } }

Invocation process for non streaming plain text output#

1. The mutation step is identical to the one inside the invocation process for streaming output. I.e. send mutation fz_zai_create_conversation(inputArgs: $inputArgs, zaiConfigId: $zaiConfigId) to obtain the conversation id.

2. There will be no messages in the STREAMING state. i.e. A message of IN_PROGRESS status will be sent by the server, followed directly by the COMPLETED message with the final result.

Invocation process for AI agents that use models with image output#

Certain model support image output, like gemini-2.5-flash-image.

Their invocation process is the same as the plain text ones. Except that in the COMPLETED message, the field images will be filled with content. The images Their output will be no different from plain-text only outputs, regardless of the streaming setting. Their COMPLETED message looks like:

json

{
  "data": {
    "fz_zai_listen_conversation_result": {
      "__typename": "ConversationResult",
      "conversationId": 1494,
      "data": "I merged the three images into one, combining elements from each to create a new, unique image.\n",
      "images": [
        {
          "__typename": "FZ_Image",
          "id": 1020000000000164
        }
      ],
      "reasoningContent": null,
      "status": "COMPLETED"
    }
  }
}

The ids for FZ_Image in images represent the ids in Zion's file / asset system. Refer to zion-binary-asset-upload-rules

Invocation process for structured output#

AI agents with structured output cannot be streaming. They also always come with a JSONSchema in their configuration.

json

{
  "output": {
      "type": "object",
      "properties": {
        "httpLink": {
          "type": "string"
        },
        "reasoning": {
          "type": "string"
        }
      },
      "required": [
        "httpLink",
        "reasoning"
      ]
    }
}

There will be no messages from the GraphQL server that are in the "STREAMING" state. There will be one "COMPLETED" message where the data field is a JSON that satisfies the JSONSchema. e.g.

json

{
  "httplink": "https://www.google.com/calendar/event?eid=MTcxN2U3cHAzaDFtYTdxYzd0bGV0aHNvYmsgamlhbmd5YW9rYWlqb2huQG0",
  "explanation": "No existing events were found on 2025-10-24 in America/Los_Angeles, so there are no conflicts. Preference is mornings; scheduled 08:00–08:10 at Los Altos High school. With no adjacent events, transit checks to previous and next events are trivially satisfied."
}

Continuing conversation#

After AI Agent returns result (status = COMPLETED), the conversation can be continued by calling fz_zai_send_ai_message. The subscription of fz_zai_listen_conversation_result on the same conversationId will continue to receive messages.

e.g.

mutation request:

gql

mutation continue($conversationId: Long!, $text: String) {
  fz_zai_send_ai_message(conversationId: $conversationId, text: $text)
}

Variables:

json

{
  "conversationId": 1480,
  "text": "make it about the sun"
}

The response from the corresponding fz_zai_listen_conversation_result will then continue. Similar to what happens after one initiates a converation with an AI agent, going through the same IN_PROGRESS -> (STREAMING) -> COMPLETED status transition.

Stopping conversation#

For converations still in "IN_PROGRESS" or "STREAMING" states, they can be stopped by calling fz_zai_stop_responding, which always returns true. When called on conversations with "COMPLETED" state, a 400 error will be thrown inside the errors field of the GraphQL response. e.g.

mutation request:

gql

mutation continue($conversationId: Long!) {
  fz_zai_stop_responding(conversationId: $conversationId)
}

Variables:

json

{
  "conversationId": 1480
}

Binary Asset Upload#

All binary assets (images, videos, files) are stored on object storage services (e.g., S3). Their storage path is recorded in Zion's database. When referencing these assets in other tables, you must store only the asset's Zion ID, not its path or URL.

Upload Workflow#

To upload a binary asset and obtain its Zion ID, you must follow a strict two-step process:

Step 1: Obtain a Presigned Upload URL

1. Calculate the MD5 hash of the file (raw 128-bit hash), then Base64-encode it.

2. Call the appropriate GraphQL mutation to request a presigned upload URL. Use the mutation that matches your asset type:

   • imagePresignedUrl for images
   • videoPresignedUrl for videos
   • filePresignedUrl for other files

Provide:

• The Base64-encoded MD5 hash
• The file format/suffix (see MediaFormat below)
• (Optional) Access control (see CannedAccessControlList below)

Example GraphQL Mutations

graphql

mutation GetImageUploadUrl($md5: String!, $suffix: MediaFormat!, $acl: CannedAccessControlList) {
  imagePresignedUrl(imgMd5Base64: $md5, imageSuffix: $suffix, acl: $acl) {
    imageId
    uploadUrl
    uploadHeaders
  }
}

mutation GetVideoUploadUrl($md5: String!, $format: MediaFormat!, $acl: CannedAccessControlList) {
  videoPresignedUrl(videoMd5Base64: $md5, videoFormat: $format, acl: $acl) {
    videoId
    uploadUrl
    uploadHeaders
  }
}

mutation GetFileUploadUrl($md5: String!, $format: MediaFormat!, $name: String, $suffix: String, $sizeBytes: Int, $acl: CannedAccessControlList) {
  filePresignedUrl(
    md5Base64: $md5
    format: $format
    name: $name
    suffix: $suffix
    sizeBytes: $sizeBytes
    acl: $acl
  ) {
    fileId
    uploadHeaders
    uploadUrl
  }
}

• CannedAccessControlList (recommended: PRIVATE):

  • AUTHENTICATE_READ, AWS_EXEC_READ, BUCKET_OWNER_FULL_CONTROL, BUCKET_OWNER_READ, DEFAULT, LOG_DELIVERY_WRITE, PRIVATE, PUBLIC_READ, PUBLIC_READ_WRITE

• MediaFormat:

  • CSS, CSV, DOC, DOCX, GIF, HTML, ICO, JPEG, JPG, JSON, MOV, MP3, MP4, OTHER, PDF, PNG, PPT, PPTX, SVG, TXT, WAV, WEBP, XLS, XLSX, XML

Step 2: Upload the File and Use the Returned ID

1. The mutation response includes:

   • The asset's unique ID ( imageId, videoId, or fileId)
   • A presigned uploadUrl
   • Any required uploadHeaders

2. Upload the file:

   • Perform an HTTP PUT request to the uploadUrl with the raw file data
   • Include any uploadHeaders from the mutation response

3. Reference the asset:

   • Use the returned ID as the value for the corresponding *_id field in your Zion data mutation (e.g., cover_image_id: returnedImageId)

Note: This two-step process is mandatory for all media uploads in Zion.app.

Third-Party APIs#

A project built on Zion.app can have many third-party HTTP APIs imported. These are separated into two categories: query or mutation, roughly (though not always the case) corresponding to the semantics of HTTP GET vs POST.

Each API is stored in the following data structure:

typescript

type ScalarType = 'string' | 'boolean' | 'number' | 'integer';
type TypeDefinition =
  | ScalarType
  | { [key: string]: TypeDefinition | TypeDefinition[] };

interface ThirdPartyApiConfig {
  id: string;
  name: string;
  operation: 'query' | 'mutation';
  inputs: { [key: string]: TypeDefinition };
  outputs: { [key: string]: TypeDefinition };
}

N.B. The value of the operation field within ThirdPartyApiConfig determines the root GraphQL field. i.e. query -> query operation_${id}, and mutation -> mutation operation_${id}.

Invocation process#

Each input should be provided unless the user asks to remove it.

e.g. Given TPA configuration as follows:

json

      {
        "id": "lzb3ownk",
        "inputs": {
          "body": {
            "summary": "string",
            "location": "string",
            "description": "string",
            "start": {
              "dateTime": "string",
              "timeZone": "string"
            },
            "end": {
              "dateTime": "string",
              "timeZone": "string"
            },
            "attendees": [
              "string"
            ]
          },
          "Authorization": "string"
        },
        "outputs": {
          "body": {
            "kind": "string",
            "etag": "string",
            "id": "string",
            "status": "string",
            "htmlLink": "string",
            "created": "string",
            "updated": "string",
            "summary": "string",
            "description": "string",
            "location": "string",
            "creator": {
              "email": "string",
              "self": "boolean"
            },
            "organizer": {
              "email": "string",
              "self": "boolean"
            },
            "start": {
              "dateTime": "string",
              "timeZone": "string"
            },
            "end": {
              "dateTime": "string",
              "timeZone": "string"
            },
            "iCalUID": "string",
            "sequence": "number",
            "reminders": {
              "useDefault": "boolean"
            },
            "eventType": "string"
          }
        },
        "operation": "mutation"
      }

The corresponding GraphQL query should be

gql

mutation request_${nonce}($summary: String, $location: String, $description: String, $start_dateTime: String, $start_timeZone: String, $end_dateTime: String, $end_timeZone: String, $attendees:[String], $Authorization: String) {
  operation_lzb3ownk(fz_body: {}, arg1: $_1, arg2: $_2) {
    responseCode
    field_200_json {
      {subFieldSelections}
    }
 }
}

field_200_json is a fixed fields for all third-party API derived GraphQL operation. It means the response that's valid for all 2xx response codes.

The responseCode subfield should always be checked, in case 5xx or 4xx codes are returned, which means field_200_json would be empty.