OpenParable
Skip to content
← Back to skills

Steedos Graphql API

Development
steedos-graphql-api

Steedos Graphql API is an Agent Skill for development published in the steedos/steedos-platform repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Steedos GraphQL API auto-generated from object metadata at /graphql. TRIGGER: POST /graphql; {object}, {object}__findOne, {object}__count, {object}__insert, {object}__update, {object}__delete; __expand (lookup expansion), _display (formatted values), _permissions (record permissions), _related_* (related records); filters/pagination/sorting in GraphQL; Apollo Playground. SKIP: REST CRUD → steedos-server-api or steedos-builder6-api; server functions → steedos-server-logic.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/steedos/steedos-platform/blob/HEAD/skills/steedos-graphql-api/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/steedos-graphql-api, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Steedos GraphQL API | Steedos GraphQL 接口

Overview | 概述

Steedos provides a GraphQL API that is auto-generated from object metadata. Every Steedos object automatically gets GraphQL queries and mutations — no manual schema definition required. The schema updates dynamically when objects or fields change.

Steedos 提供的 GraphQL API 根据对象元数据自动生成。每个 Steedos 对象自动获得 GraphQL 查询和变更操作,无需手动定义 Schema。对象或字段变更时 Schema 自动更新。

Endpoint | 端点

POST /graphql
  • Authentication: Authorization: Bearer {token} header, or cookie-based session
  • Content-Type: application/json
  • Apollo Playground: Enabled by default at /graphql (controlled by STEEDOS_GRAPHQL_ENABLE_CONSOLE)

Queries | 查询

For each object (e.g., orders), three queries are auto-generated:

List Records — {objectName}

{
  orders(
    filters: [["status", "=", "approved"]]
    fields: ["_id", "name", "amount"]
    top: 20
    skip: 0
    sort: "created desc"
  ) {
    _id
    name
    amount
    status
  }
}

Find One — {objectName}__findOne

{
  orders__findOne(id: "67abc123def456") {
    _id
    name
    amount
    customer
  }
}

Count — {objectName}__count

{
  orders__count(filters: [["status", "=", "draft"]])
}

Query Parameters | 查询参数

ParameterTypeRequiredDefaultDescription
filtersJSONNononeOData-style filter array, e.g. [["name", "contains", "test"]]
fieldsJSONNoallArray of field names to return
topIntYes10000Max records to return (max 10,000)
skipIntYes0Pagination offset
sortStringNononeSort expression, e.g. "created desc", "name asc, amount desc"

Filter Operators | 筛选运算符

=, !=, >, >=, <, <=
contains, notcontains, startswith
in, notin
between

Example filters:

[["status", "=", "active"]]
[["amount", ">", 1000], ["status", "in", ["draft", "submitted"]]]
[["name", "contains", "test"]]

Mutations | 变更

Insert — {objectName}__insert

mutation {
  orders__insert(doc: {
    name: "ORD-2026-001",
    customer: "cust_abc123",
    amount: 5000,
    status: "draft"
  }) {
    _id
    name
    amount
  }
}

The space field is auto-injected from the authenticated user's session.

Update — {objectName}__update

mutation {
  orders__update(
    id: "67abc123def456",
    doc: { status: "approved", approved_at: "2026-04-23T10:00:00Z" }
  ) {
    _id
    name
    status
  }
}

Delete — {objectName}__delete

mutation {
  orders__delete(id: "67abc123def456")
}

Respects the object's enable_trash setting — soft-delete or hard-delete accordingly.

Special Fields | 特殊字段

Lookup Expansion — __expand

Expand lookup/master_detail references to get the full related record:

{
  orders__findOne(id: "67abc123def456") {
    _id
    name
    customer              # Returns raw ID: "cust_abc123"
    customer__expand {    # Returns expanded object
      _id
      name
      email
      phone
    }
  }
}

Display Formatting — _display

Get localized, formatted field values:

{
  orders__findOne(id: "67abc123def456") {
    _id
    amount                # Raw value: 5000
    status                # Raw value: "approved"
    _display {
      amount              # Formatted: "¥5,000.00"
      status              # Localized label: "已批准"
      created             # Formatted date: "2026-04-23 10:00"
    }
  }
}

Record Permissions — _permissions

Check what the current user can do with a record:

{
  orders__findOne(id: "67abc123def456") {
    _id
    name
    _permissions {
      allowCreate
      allowEdit
      allowDelete
      field_permissions
    }
  }
}

Related Records — _related_*

Access related child records, files, tasks, etc.:

{
  orders__findOne(id: "67abc123def456") {
    _id
    name
    _related_order_items_order {  # Detail records via lookup field "order"
      _id
      product
      quantity
      price
    }
    _related_files {
      _id
      name
    }
    _related_tasks {
      _id
      name
      status
    }
    _related_notes {
      _id
      body
    }
  }
}

Related field naming: _related_{childObjectName}_{lookupFieldName}

Field Type Mapping | 字段类型映射

Steedos Field TypeGraphQL Type
text, textarea, html, url, emailString
number, currency, percentFloat
booleanBoolean
date, datetime, timeDate
select (single)String
select (multiple)[String]
lookup, master_detailJSON (raw) + __expand (referenced type)
image, fileJSON
formula, summaryDepends on return type
OtherJSON

Authentication | 认证

GraphQL requests require authentication via one of:

# Bearer token
curl -X POST /graphql \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ space_users { _id name } }"}'

# Cookie-based session (from browser)
# Cookies: X-Space-Id, X-Auth-Token

Unauthenticated requests return UnAuthorizedError.

DataLoader Batching | DataLoader 批量优化

GraphQL queries automatically use DataLoader to batch and cache database lookups within a single request, preventing N+1 query problems when expanding lookup fields.

Controlled by environment variable:

STEEDOS_GRAPHQL_ENABLE_DATALOADER=true  # default

Complete Example | 完整示例

# Fetch orders with expanded customer, display values, and permissions
{
  orders(
    filters: [["status", "in", ["submitted", "approved"]], ["amount", ">", 1000]]
    sort: "amount desc"
    top: 10
  ) {
    _id
    name
    amount
    status
    order_date
    customer__expand {
      _id
      name
      phone
    }
    _display {
      amount
      status
      order_date
    }
    _permissions {
      allowEdit
      allowDelete
    }
  }
}
# Create an order and return the new record
mutation {
  orders__insert(doc: {
    name: "ORD-2026-042",
    customer: "cust_abc123",
    amount: 8500,
    status: "draft",
    order_date: "2026-04-23"
  }) {
    _id
    name
    amount
    customer__expand {
      name
    }
  }
}

Environment Variables | 环境变量

VariableDefaultDescription
STEEDOS_GRAPHQL_ENABLE_CONSOLEtrueEnable Apollo Playground at /graphql
STEEDOS_GRAPHQL_ENABLE_DATALOADERtrueEnable DataLoader batching

Limitations | 限制

  • Max 10,000 records per query (top parameter)
  • Max 10MB request/response body
  • No subscriptions (real-time updates use WebSocket instead, see steedos-server-internals)
  • Deleted records (is_deleted: true) are excluded by default