{
  "openapi": "3.1.0",
  "info": {
    "title": "Airsurf API",
    "version": "2026-10-22",
    "description": "Everything a workspace offers over HTTP: issues, teams and webhooks; the ecosystem graph (search, links, other apps' objects, events, apps, rules, connections); and Docs pages, blocks, databases and comments (Notion's shapes). Authorize with an API key from Settings → API (Authorization: Bearer zv_secret_…); it acts as the person who made it and never sees more than they do. Every answer carries X-Request-Id; POSTs take an Idempotency-Key.",
    "contact": {
      "name": "Airsurf developers",
      "url": "https://airsurf.app/developers"
    }
  },
  "externalDocs": {
    "description": "Reference",
    "url": "https://airsurf.app/developers"
  },
  "servers": [
    {
      "url": "https://airsurf.app/api"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "tags": [
    {
      "name": "Tasks",
      "description": "Issues and their comments"
    },
    {
      "name": "Teams",
      "description": "Teams and their statuses"
    },
    {
      "name": "Webhooks",
      "description": "Signed HTTPS deliveries of what changes, and a live stream for your terminal"
    },
    {
      "name": "Workspace",
      "description": "Who the integration is"
    },
    {
      "name": "Graph",
      "description": "Search, cards, related objects and links across products"
    },
    {
      "name": "Projects",
      "description": "Teams, projects and issues"
    },
    {
      "name": "Objects",
      "description": "Your apps' objects in the workspace"
    },
    {
      "name": "Events",
      "description": "What changed, as a feed and as webhooks; your app's own events"
    },
    {
      "name": "Apps",
      "description": "What each connected app keeps, sends and does (its manifest)"
    },
    {
      "name": "Runs",
      "description": "Actions asked of an app: by a rule, a person or another app"
    },
    {
      "name": "Rules",
      "description": "When something happens in one app, do something in another"
    },
    {
      "name": "Connections",
      "description": "Any service connected through Airsurf: found by its name or address, signed in with one click or a key, kept in step"
    },
    {
      "name": "Docs",
      "description": "Pages, blocks, databases, data sources, comments and people (Notion's shapes; Zvena-Version 2022-06-28 or 2025-09-03)"
    },
    {
      "name": "Tables",
      "description": "Tables data and reports"
    }
  ],
  "paths": {
    "/v1/teams": {
      "get": {
        "operationId": "listTaskTeams",
        "summary": "Teams issues can be filed in, with their statuses",
        "tags": [
          "Teams"
        ],
        "x-zvena-scope": "read",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TaskTeam"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/teams/{id}": {
      "get": {
        "operationId": "getTaskTeam",
        "summary": "One team, with its statuses",
        "tags": [
          "Teams"
        ],
        "x-zvena-scope": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The team's id, or its key (ENG)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskTeam"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/tasks": {
      "get": {
        "operationId": "listTasks",
        "summary": "Issues, newest change first, a page at a time",
        "tags": [
          "Tasks"
        ],
        "x-zvena-scope": "read",
        "description": "Only the issues the key's maker may see (private teams stay private). Descriptions are left out (\"\") unless description=true.",
        "parameters": [
          {
            "name": "team",
            "in": "query",
            "required": false,
            "description": "Team ids or keys, comma-separated",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Status ids, or categories (backlog, unstarted, started, completed, canceled), comma-separated",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assignee",
            "in": "query",
            "required": false,
            "description": "Member ids, me or none, comma-separated",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "project",
            "in": "query",
            "required": false,
            "description": "Project ids or none, comma-separated",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "label",
            "in": "query",
            "required": false,
            "description": "Label ids, comma-separated",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "priority",
            "in": "query",
            "required": false,
            "description": "0 (none) … 4 (low), comma-separated",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Words to find, or an identifier",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "archived",
            "in": "query",
            "required": false,
            "description": "true: archived issues instead",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "description": "Only issues changed since then (with order=updated)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "updated (default), created, priority, manual or due",
            "schema": {
              "enum": [
                "updated",
                "created",
                "priority",
                "manual",
                "due"
              ]
            }
          },
          {
            "name": "description",
            "in": "query",
            "required": false,
            "description": "true: include each issue's description",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "1–100 (50)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "start_cursor",
            "in": "query",
            "required": false,
            "description": "A next_cursor this list gave",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Task"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "operationId": "createTask",
        "summary": "File an issue",
        "tags": [
          "Tasks"
        ],
        "x-zvena-scope": "write",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/tasks/{id}": {
      "get": {
        "operationId": "getTask",
        "summary": "One issue, with its description",
        "tags": [
          "Tasks"
        ],
        "x-zvena-scope": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The issue's id, or its identifier (ENG-123)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "ETag": {
                "description": "This state of the issue: send it as If-Match with a change",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "patch": {
        "operationId": "updateTask",
        "summary": "Change an issue (its status, title, assignee…)",
        "tags": [
          "Tasks"
        ],
        "x-zvena-scope": "write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The issue's id, or its identifier (ENG-123)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IfMatch"
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "ETag": {
                "description": "This state of the issue: send it as If-Match with a change",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/tasks/{id}/comments": {
      "get": {
        "operationId": "listTaskComments",
        "summary": "An issue's comments, oldest first",
        "tags": [
          "Tasks"
        ],
        "x-zvena-scope": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The issue's id, or its identifier (ENG-123)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "1–100 (50)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "start_cursor",
            "in": "query",
            "required": false,
            "description": "A next_cursor this list gave",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TaskComment"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "operationId": "createTaskComment",
        "summary": "Comment on an issue (or reply in a thread)",
        "tags": [
          "Tasks"
        ],
        "x-zvena-scope": "write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The issue's id, or its identifier (ENG-123)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "body"
                ],
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "Markdown"
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "A comment of the same issue: the reply joins its thread"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskComment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "operationId": "listWebhooks",
        "summary": "The webhooks the key's maker manages",
        "tags": [
          "Webhooks"
        ],
        "x-zvena-scope": "events",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Webhook"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      },
      "post": {
        "operationId": "createWebhook",
        "summary": "Add a webhook (its signing secret is answered this once)",
        "tags": [
          "Webhooks"
        ],
        "x-zvena-scope": "events + write",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Webhook"
                    },
                    {
                      "type": "object",
                      "required": [
                        "secret"
                      ],
                      "properties": {
                        "secret": {
                          "type": "string",
                          "description": "zv_whsec_…: keep it with your endpoint"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/webhooks/listen": {
      "get": {
        "operationId": "listenWebhooks",
        "summary": "The workspace's events as Server-Sent Events (airsurf webhooks listen)",
        "tags": [
          "Webhooks"
        ],
        "x-zvena-scope": "events",
        "description": "A stream of `ready` (the key's listen secret), then `delivery` messages: { id, type, payload, signature } — payload is the exact body a webhook gets, signature its Zvena-Signature with the listen secret. A comment every 25 s; the stream ends after an hour (open a new one). Three streams per key and ten per workspace at once.",
        "parameters": [
          {
            "name": "events",
            "in": "query",
            "required": false,
            "description": "Comma-separated: task.created, task.updated, task.deleted, task.commented, page.updated, comment.added (default: all the key's products allow)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "text/event-stream",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "get": {
        "operationId": "getWebhook",
        "summary": "One webhook",
        "tags": [
          "Webhooks"
        ],
        "x-zvena-scope": "events",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "wh_…",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "patch": {
        "operationId": "updateWebhook",
        "summary": "Change a webhook, or turn it off and on",
        "tags": [
          "Webhooks"
        ],
        "x-zvena-scope": "events + write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "wh_…",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "operationId": "deleteWebhook",
        "summary": "Remove a webhook and its delivery log",
        "tags": [
          "Webhooks"
        ],
        "x-zvena-scope": "events + write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "wh_…",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Webhook"
                    },
                    {
                      "type": "object",
                      "required": [
                        "deleted"
                      ],
                      "properties": {
                        "deleted": {
                          "const": true
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/users": {
      "get": {
        "operationId": "listUsers",
        "summary": "The workspace's people and bots",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "users",
        "parameters": [
          {
            "name": "start_cursor",
            "in": "query",
            "required": false,
            "description": "A next_cursor this list gave",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "1–100 (50)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DocsObject"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/users/me": {
      "get": {
        "operationId": "getBotUser",
        "summary": "The integration's bot user",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "any",
        "parameters": [
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/users/{id}": {
      "get": {
        "operationId": "getUser",
        "summary": "One person or bot",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "users",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/search": {
      "post": {
        "operationId": "searchDocs",
        "summary": "Pages and databases shared with the integration, by title",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DocsObject"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/pages": {
      "post": {
        "operationId": "createPage",
        "summary": "A sub-page or a database row",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "insert",
        "parameters": [
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/pages/{id}": {
      "get": {
        "operationId": "getPage",
        "summary": "A page with its properties",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "patch": {
        "operationId": "updatePage",
        "summary": "Change a page's properties, icon, cover, or trash it",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "update",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/pages/{id}/properties/{property_id}": {
      "get": {
        "operationId": "getPageProperty",
        "summary": "One property value (lists paginated)",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "property_id",
            "in": "path",
            "required": true,
            "description": "The property's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/blocks/{id}": {
      "get": {
        "operationId": "getBlock",
        "summary": "A block",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "patch": {
        "operationId": "updateBlock",
        "summary": "Change a block's content",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "update",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "operationId": "deleteBlock",
        "summary": "Move a block to the trash",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "update",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/blocks/{id}/children": {
      "get": {
        "operationId": "listBlockChildren",
        "summary": "The blocks of a page or under a block",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_cursor",
            "in": "query",
            "required": false,
            "description": "A next_cursor this list gave",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "1–100 (50)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DocsObject"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "patch": {
        "operationId": "appendBlockChildren",
        "summary": "Append blocks (after a child, or at the end)",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "insert",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DocsObject"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/databases": {
      "post": {
        "operationId": "createDatabase",
        "summary": "A new database inside a page",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "insert",
        "parameters": [
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/databases/{id}": {
      "get": {
        "operationId": "getDatabase",
        "summary": "A database and its properties",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "patch": {
        "operationId": "updateDatabase",
        "summary": "Rename it, or add, change or remove properties",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "update",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/databases/{id}/query": {
      "post": {
        "operationId": "queryDatabase",
        "summary": "A database's rows (filter, sorts, pages)",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DocsObject"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/data_sources": {
      "post": {
        "operationId": "createDataSource",
        "summary": "A further data source in a database",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "insert",
        "parameters": [
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/data_sources/{id}": {
      "get": {
        "operationId": "getDataSource",
        "summary": "A data source and its properties",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "patch": {
        "operationId": "updateDataSource",
        "summary": "Change a data source",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "update",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/data_sources/{id}/query": {
      "post": {
        "operationId": "queryDataSource",
        "summary": "A data source's rows",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DocsObject"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/data_sources/{id}/templates": {
      "get": {
        "operationId": "listDataSourceTemplates",
        "summary": "A data source's page templates",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A UUID (with or without dashes)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DocsObject"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/comments": {
      "get": {
        "operationId": "listDocsComments",
        "summary": "Open discussions of a page or a block",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "readComments",
        "parameters": [
          {
            "name": "block_id",
            "in": "query",
            "required": false,
            "description": "A page or block id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_cursor",
            "in": "query",
            "required": false,
            "description": "A next_cursor this list gave",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "1–100 (50)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DocsObject"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send it as start_cursor for the next page; null: the last page"
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "operationId": "createDocsComment",
        "summary": "A new comment on a page, or a reply",
        "tags": [
          "Docs"
        ],
        "x-zvena-capability": "insertComments",
        "parameters": [
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/tables/datasets": {
      "get": {
        "operationId": "listDatasets",
        "summary": "The workspace's Tables data with their fields",
        "tags": [
          "Tables"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Where to go on",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/tables/datasets/{id}/rows": {
      "get": {
        "operationId": "listDatasetRows",
        "summary": "A dataset's current rows",
        "tags": [
          "Tables"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The dataset's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Where to go on",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 1000",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "operationId": "writeDatasetRows",
        "summary": "Upsert or append rows (up to 5000)",
        "tags": [
          "Tables"
        ],
        "x-zvena-capability": "insert",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The dataset's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/tables/reports": {
      "get": {
        "operationId": "listReports",
        "summary": "The workspace's Tables reports",
        "tags": [
          "Tables"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Where to go on",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/tables/reports/{id}": {
      "get": {
        "operationId": "getReport",
        "summary": "A report's numbers as computed",
        "tags": [
          "Tables"
        ],
        "x-zvena-capability": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The report's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "description": "month:YYYY-MM-01 or all",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Version",
            "in": "header",
            "required": false,
            "description": "The Docs API's version: 2022-06-28 (default) or 2025-09-03 (data sources). Notion-Version is read too.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/me": {
      "get": {
        "operationId": "getMe",
        "summary": "The integration, its workspace, plan and scopes",
        "tags": [
          "Workspace"
        ],
        "x-zvena-scope": "read",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/search": {
      "get": {
        "operationId": "search",
        "summary": "Search every product and other apps' objects at once",
        "tags": [
          "Graph"
        ],
        "x-zvena-scope": "read",
        "description": "The best matches of each kind (a few of each), best first; empty q: recent work. has_more says page_size cut the list.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Words to find; empty: recent work",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kinds",
            "in": "query",
            "required": false,
            "description": "Comma-separated kinds: note, issue, project, design, event, user, ext",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "1–100 (20)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Card"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    },
                    "q": {
                      "type": "string",
                      "description": "The query as it was searched"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/cards": {
      "post": {
        "operationId": "getCards",
        "summary": "Cards for refs (the ones the maker may see)",
        "tags": [
          "Graph"
        ],
        "x-zvena-scope": "read",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "refs"
                ],
                "properties": {
                  "refs": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "string",
                      "description": "A ref: note:<id> (a Docs page or row), issue:<id>, project:<id>, design:<file>[/<frame>], event:<id>, user:<id> or ext:<id> (another app's object)."
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Card"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/resolve": {
      "post": {
        "operationId": "resolveLinks",
        "summary": "What links name: Airsurf links, KEY-12, refs, and URLs of other apps' objects",
        "tags": [
          "Graph"
        ],
        "x-zvena-scope": "read",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "urls"
                ],
                "properties": {
                  "urls": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Resolution"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/related": {
      "get": {
        "operationId": "getRelated",
        "summary": "Everything an object is linked with, both ways",
        "tags": [
          "Graph"
        ],
        "x-zvena-scope": "read",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "A ref: note:<id> (a Docs page or row), issue:<id>, project:<id>, design:<file>[/<frame>], event:<id>, user:<id> or ext:<id> (another app's object).",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Related"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    },
                    "ref": {
                      "type": "string"
                    },
                    "indexing": {
                      "type": "boolean",
                      "description": "The workspace is still being indexed: more may come"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/links": {
      "get": {
        "operationId": "listLinks",
        "summary": "An object's links as stored",
        "tags": [
          "Graph"
        ],
        "x-zvena-scope": "read",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "A ref: note:<id> (a Docs page or row), issue:<id>, project:<id>, design:<file>[/<frame>], event:<id>, user:<id> or ext:<id> (another app's object).",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Link"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    },
                    "ref": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "operationId": "createLink",
        "summary": "Link two objects by hand",
        "tags": [
          "Graph"
        ],
        "x-zvena-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "src",
                  "dst"
                ],
                "properties": {
                  "src": {
                    "type": "string",
                    "description": "A ref: note:<id> (a Docs page or row), issue:<id>, project:<id>, design:<file>[/<frame>], event:<id>, user:<id> or ext:<id> (another app's object)."
                  },
                  "dst": {
                    "type": "string",
                    "description": "A ref: note:<id> (a Docs page or row), issue:<id>, project:<id>, design:<file>[/<frame>], event:<id>, user:<id> or ext:<id> (another app's object)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "src",
                    "dst",
                    "via",
                    "created"
                  ],
                  "properties": {
                    "object": {
                      "const": "link"
                    },
                    "src": {
                      "type": "string"
                    },
                    "dst": {
                      "type": "string"
                    },
                    "via": {
                      "const": "manual"
                    },
                    "created": {
                      "type": "boolean",
                      "description": "false: the link was there already"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      },
      "delete": {
        "operationId": "deleteLink",
        "summary": "Remove a link made by hand or automatically (it is never made automatically again)",
        "tags": [
          "Graph"
        ],
        "x-zvena-scope": "write",
        "parameters": [
          {
            "name": "src",
            "in": "query",
            "required": true,
            "description": "A ref: note:<id> (a Docs page or row), issue:<id>, project:<id>, design:<file>[/<frame>], event:<id>, user:<id> or ext:<id> (another app's object).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dst",
            "in": "query",
            "required": true,
            "description": "A ref: note:<id> (a Docs page or row), issue:<id>, project:<id>, design:<file>[/<frame>], event:<id>, user:<id> or ext:<id> (another app's object).",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "src",
                    "dst",
                    "via",
                    "deleted"
                  ],
                  "properties": {
                    "object": {
                      "const": "link"
                    },
                    "src": {
                      "type": "string"
                    },
                    "dst": {
                      "type": "string"
                    },
                    "via": {
                      "const": "manual"
                    },
                    "deleted": {
                      "type": "boolean",
                      "description": "false: there was no such link"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/suggestions": {
      "get": {
        "operationId": "listSuggestions",
        "summary": "Links suggested for an object (a person, or the app, says yes or no)",
        "tags": [
          "Graph"
        ],
        "x-zvena-scope": "read",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "A ref: note:<id> (a Docs page or row), issue:<id>, project:<id>, design:<file>[/<frame>], event:<id>, user:<id> or ext:<id> (another app's object).",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Suggestion"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    },
                    "ref": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/suggestions/{id}": {
      "post": {
        "operationId": "answerSuggestion",
        "summary": "Answer a suggestion: yes links the two, no keeps them from being suggested again",
        "tags": [
          "Graph"
        ],
        "x-zvena-scope": "write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The suggestion's id (sug_…)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "accept"
                ],
                "properties": {
                  "accept": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "id",
                    "result"
                  ],
                  "properties": {
                    "object": {
                      "const": "suggestion"
                    },
                    "id": {
                      "type": "string"
                    },
                    "result": {
                      "enum": [
                        "linked",
                        "rejected"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/teams": {
      "get": {
        "operationId": "listTeams",
        "summary": "Teams issues can be filed in",
        "tags": [
          "Projects"
        ],
        "x-zvena-scope": "read",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Team"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/projects": {
      "get": {
        "operationId": "listProjects",
        "summary": "Projects",
        "tags": [
          "Projects"
        ],
        "x-zvena-scope": "read",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Project"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/issues": {
      "get": {
        "operationId": "listIssues",
        "summary": "A project's issues, or the maker's own",
        "tags": [
          "Projects"
        ],
        "x-zvena-scope": "read",
        "description": "Name project_id or mine=true. Open issues unless done=true. has_more says page_size cut the list.",
        "parameters": [
          {
            "name": "project_id",
            "in": "query",
            "required": false,
            "description": "A project's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mine",
            "in": "query",
            "required": false,
            "description": "true: issues assigned to the maker",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "done",
            "in": "query",
            "required": false,
            "description": "true: completed and canceled too",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "1–100 (50)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Card"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "operationId": "createIssue",
        "summary": "File an issue",
        "tags": [
          "Projects"
        ],
        "x-zvena-scope": "write",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/IssueInput"
                  },
                  {
                    "required": [
                      "team_id",
                      "title"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IssueWritten"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/issues/{id}": {
      "get": {
        "operationId": "getIssue",
        "summary": "One issue, with its description",
        "tags": [
          "Projects"
        ],
        "x-zvena-scope": "read",
        "description": "The answer's ETag names this state of the issue: send it as If-Match with a change.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The issue's id, or its identifier (ENG-12)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Issue"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "patch": {
        "operationId": "updateIssue",
        "summary": "Change an issue (status, title, priority, assignee, due date, project, links)",
        "tags": [
          "Projects"
        ],
        "x-zvena-scope": "write",
        "description": "With If-Match (the ETag of GET /v1/eco/issues/{id}) the change is made only if nobody changed the issue since: two apps editing one issue at once, the second gets 412 and reads it again.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The issue's id, or its identifier (ENG-12)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IfMatch"
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IssueInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IssueWritten"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/issues/{id}/statuses": {
      "get": {
        "operationId": "listIssueStatuses",
        "summary": "The statuses an issue can move to",
        "tags": [
          "Projects"
        ],
        "x-zvena-scope": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The issue's id, or its identifier (ENG-12)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Status"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    },
                    "current": {
                      "type": "string",
                      "description": "The id of its status now"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/objects": {
      "get": {
        "operationId": "listObjects",
        "summary": "This integration's objects, newest change first",
        "tags": [
          "Objects"
        ],
        "x-zvena-scope": "objects",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Only this type",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor of the previous page",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "1–100 (50)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ExternalObject"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/objects/{external_id}": {
      "put": {
        "operationId": "upsertObject",
        "summary": "Create or replace an object of your app",
        "tags": [
          "Objects"
        ],
        "x-zvena-scope": "objects",
        "description": "Idempotent: the same body again changes nothing (no event, no new edit time). With a `version`, a write older than the one kept changes nothing and answers 409 with stale: true and the object as kept, so deliveries that arrive out of order never put an older state back. If-Match (the ETag of the last read) writes only over that state; If-None-Match: * only creates.",
        "parameters": [
          {
            "name": "external_id",
            "in": "path",
            "required": true,
            "description": "Your app's id of the object: 1–200 visible ASCII characters, URL-encoded in the path (pr/42 → pr%2F42)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IfMatch"
          },
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalObjectInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replaced (or unchanged)",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalObject"
                }
              }
            }
          },
          "201": {
            "description": "Created",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "get": {
        "operationId": "getObject",
        "summary": "One object of your app",
        "tags": [
          "Objects"
        ],
        "x-zvena-scope": "objects",
        "parameters": [
          {
            "name": "external_id",
            "in": "path",
            "required": true,
            "description": "Your app's id of the object (URL-encoded)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "operationId": "deleteObject",
        "summary": "Delete an object (its links go too)",
        "tags": [
          "Objects"
        ],
        "x-zvena-scope": "objects",
        "description": "With ?version=, an object kept at a newer version stays (409, stale), and the deletion is remembered for a week: an older write that arrives later does not bring the object back.",
        "parameters": [
          {
            "name": "external_id",
            "in": "path",
            "required": true,
            "description": "Your app's id of the object (URL-encoded)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "query",
            "required": false,
            "description": "The object's version in your app when it was deleted (a number or a date-time)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IfMatch"
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ExternalObject"
                    },
                    {
                      "type": "object",
                      "required": [
                        "deleted"
                      ],
                      "properties": {
                        "deleted": {
                          "const": true
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/objects/batch": {
      "post": {
        "operationId": "upsertObjects",
        "summary": "Create or replace up to 100 objects",
        "tags": [
          "Objects"
        ],
        "x-zvena-scope": "objects",
        "description": "Each object is saved on its own: a bad one gets an error row with its index, and the rest are saved. Results come in the order sent.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "objects"
                ],
                "properties": {
                  "objects": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/ExternalObjectInput"
                        },
                        {
                          "type": "object",
                          "required": [
                            "external_id"
                          ],
                          "properties": {
                            "external_id": {
                              "type": "string",
                              "description": "Your app's id of the object"
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "$ref": "#/components/schemas/BatchSaved"
                          },
                          {
                            "$ref": "#/components/schemas/BatchError"
                          }
                        ]
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/events": {
      "get": {
        "operationId": "listEvents",
        "summary": "The event feed (poll with a cursor)",
        "tags": [
          "Events"
        ],
        "x-zvena-scope": "events",
        "description": "Without after the feed starts now: no results, and next_cursor to poll from. With after: the events since, oldest first; keep next_cursor for the next poll. The feed keeps a week; an older cursor answers 410 cursor_expired.",
        "parameters": [
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "A cursor (next_cursor); without it the feed starts now",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "types",
            "in": "query",
            "required": false,
            "description": "Comma-separated event types",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "1–100 (50)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "required": [
                        "object",
                        "results",
                        "next_cursor",
                        "has_more"
                      ],
                      "properties": {
                        "object": {
                          "const": "list"
                        },
                        "results": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Event"
                          }
                        },
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                        },
                        "has_more": {
                          "type": "boolean",
                          "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                        }
                      }
                    },
                    {
                      "properties": {
                        "next_cursor": {
                          "type": "string"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "410": {
            "$ref": "#/components/responses/CursorExpired"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "operationId": "sendEvent",
        "summary": "Send an event of your app (something that happened: a payment arrived, a build failed)",
        "tags": [
          "Events"
        ],
        "x-zvena-scope": "objects",
        "description": "Rules on your app hear it once (when: app, on: event) and other apps read it in their feed as app.event. type should be one of your manifest's events when the manifest lists any. external_id names one of your objects the event is about: its fields join the event's data in rules. Up to 600 a minute.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "pattern": "^[a-z][a-z0-9_.-]{0,63}$",
                    "examples": [
                      "payment.received",
                      "deal.won"
                    ]
                  },
                  "external_id": {
                    "type": "string",
                    "description": "One of your objects the event is about"
                  },
                  "data": {
                    "type": "object",
                    "maxProperties": 30,
                    "additionalProperties": {
                      "type": [
                        "string",
                        "number",
                        "boolean",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sent",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppEvent"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/app": {
      "get": {
        "operationId": "getApp",
        "summary": "Your app's manifest: what it keeps, sends and does",
        "tags": [
          "Apps"
        ],
        "x-zvena-scope": "any",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/App"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      },
      "put": {
        "operationId": "putApp",
        "summary": "Say what your app is: object types, events, actions",
        "tags": [
          "Apps"
        ],
        "x-zvena-scope": "any",
        "description": "Rules offer your events as \"when\" and your actions as \"then\"; runs are checked against your actions' inputs. The first manifest with an action sent to a URL answers with signing_secret, once: runs POSTed to you are signed with it (see the run webhook). rotate_secret=1 makes a new one.",
        "parameters": [
          {
            "name": "rotate_secret",
            "in": "query",
            "required": false,
            "description": "1: a new signing secret (the old one stops at once)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Manifest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/App"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "signing_secret": {
                          "type": "string",
                          "description": "zv_actsec_… — only when it was made now"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "operationId": "deleteApp",
        "summary": "Remove your app's manifest (its objects stay)",
        "tags": [
          "Apps"
        ],
        "x-zvena-scope": "any",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/App"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/apps": {
      "get": {
        "operationId": "listApps",
        "summary": "The workspace's apps and what each offers",
        "tags": [
          "Apps"
        ],
        "x-zvena-scope": "read",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/App"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/apps/{app_id}/actions/{action}": {
      "post": {
        "operationId": "runAction",
        "summary": "Run another app's action",
        "tags": [
          "Runs"
        ],
        "x-zvena-scope": "actions",
        "description": "Starts a run with the maker's rights (they should edit the workspace). It is sent to the app, or waits for the app to collect it; read how it went with GET /v1/eco/runs/{id}. Up to 120 runs a minute in a workspace.",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "The app's integration id (GET /v1/eco/apps)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "action",
            "in": "path",
            "required": true,
            "description": "One of its actions",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "input": {
                    "type": "object",
                    "additionalProperties": {
                      "type": [
                        "string",
                        "number",
                        "boolean",
                        "null"
                      ]
                    }
                  },
                  "subject": {
                    "type": "string",
                    "description": "What the run is about, shown to the app when its maker may see it. A ref: note:<id> (a Docs page or row), issue:<id>, project:<id>, design:<file>[/<frame>], event:<id>, user:<id> or ext:<id> (another app's object)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Started",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Run"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/runs": {
      "get": {
        "operationId": "listRuns",
        "summary": "Runs asked of your app; claim=1 collects the ones waiting",
        "tags": [
          "Runs"
        ],
        "x-zvena-scope": "any",
        "description": "For an app that cannot be reached (its actions have no url): claim=1 returns its queued runs and marks them claimed. Report each with POST /v1/eco/runs/{id}; a run claimed and not reported for 10 minutes is offered again (5 times at most).",
        "parameters": [
          {
            "name": "claim",
            "in": "query",
            "required": false,
            "description": "1: collect queued runs",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "queued, sent, claimed, succeeded, failed or canceled",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "1–100 (20)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Run"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/runs/{id}": {
      "get": {
        "operationId": "getRun",
        "summary": "One run asked of your app, or one it started",
        "tags": [
          "Runs"
        ],
        "x-zvena-scope": "any",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "run_…",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Run"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "operationId": "reportRun",
        "summary": "Say how a run went",
        "tags": [
          "Runs"
        ],
        "x-zvena-scope": "any",
        "description": "For a run you claimed, or one you answered 202 to. An object in the answer becomes one of your objects (PUT /v1/eco/objects shape, with external_id), linked to what started the run.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "run_…",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "enum": [
                      "succeeded",
                      "failed"
                    ]
                  },
                  "result": {
                    "type": "object",
                    "description": "Anything worth keeping (up to 2 KB)"
                  },
                  "object": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/ExternalObjectInput"
                      },
                      {
                        "type": "object",
                        "required": [
                          "external_id"
                        ],
                        "properties": {
                          "external_id": {
                            "type": "string"
                          }
                        }
                      }
                    ]
                  },
                  "error": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Run"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/rules": {
      "get": {
        "operationId": "listRules",
        "summary": "Rules on apps, and rules that run apps' actions",
        "tags": [
          "Rules"
        ],
        "x-zvena-scope": "actions",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Rule"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/rules/{id}": {
      "put": {
        "operationId": "putRule",
        "summary": "Create or replace a rule across apps",
        "tags": [
          "Rules"
        ],
        "x-zvena-scope": "actions",
        "description": "When one app's object changes or it sends an event (or a Docs row, an issue, a number changes), if a condition holds (always, a comparison, or a yes/no question to Airsurf's decision model about chosen fields), then run another app's action (or file an issue, set a field). A rule that runs an app's action asks a person in Airsurf before each run; only the workspace's owner lets one act by itself, in Airsurf.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Your id for it: 6–64 letters, digits, '_' or '-'",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RuleInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replaced",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Rule"
                }
              }
            }
          },
          "201": {
            "description": "Created",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Rule"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "operationId": "deleteRule",
        "summary": "Delete a rule across apps",
        "tags": [
          "Rules"
        ],
        "x-zvena-scope": "actions",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The rule's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Rule"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/connections": {
      "get": {
        "operationId": "listConnections",
        "summary": "Services connected to the workspace (any software)",
        "tags": [
          "Connections"
        ],
        "x-zvena-scope": "read",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Connection"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      },
      "post": {
        "operationId": "createConnection",
        "summary": "Start connecting a found service",
        "tags": [
          "Connections"
        ],
        "x-zvena-scope": "write",
        "description": "Its next step says what is needed: signin (the person opens the URL and signs in on the service's page: one click), key (POST …/access with the key the person gives), site (the customer's own address of a SaaS), or try.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "found",
                  "way"
                ],
                "properties": {
                  "found": {
                    "type": "string",
                    "description": "The id findService returned"
                  },
                  "way": {
                    "enum": [
                      "registry",
                      "mcp",
                      "oauth",
                      "spec",
                      "key",
                      "basic",
                      "docs"
                    ]
                  },
                  "site": {
                    "type": "string",
                    "description": "The customer's own site of a SaaS"
                  },
                  "name": {
                    "type": "string"
                  },
                  "key_header": {
                    "type": "string",
                    "description": "For a key: its header (default Authorization)"
                  },
                  "key_prefix": {
                    "type": "string",
                    "description": "For a key: its prefix (default \"Bearer \" in Authorization)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Connection"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/connections/find": {
      "post": {
        "operationId": "findService",
        "summary": "Find how to connect a service",
        "tags": [
          "Connections"
        ],
        "x-zvena-scope": "write",
        "description": "Any service by its name or address (a SaaS, an internal tool's site, an MCP server's URL, an OpenAPI description's URL). Airsurf looks for its MCP server, its API description and its sign-in, and says the ways to connect it, best first.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "q"
                ],
                "properties": {
                  "q": {
                    "type": "string",
                    "description": "The service's name or address"
                  },
                  "link": {
                    "type": "string",
                    "description": "An Airsurf Link's id, for a service only it reaches (localhost, an office network)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FoundService"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/connections/{id}": {
      "get": {
        "operationId": "getConnection",
        "summary": "One connection",
        "tags": [
          "Connections"
        ],
        "x-zvena-scope": "read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The connection's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Connection"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "patch": {
        "operationId": "updateConnection",
        "summary": "Who sees a connection, how often it syncs, which lists, paused",
        "tags": [
          "Connections"
        ],
        "x-zvena-scope": "write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The connection's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "visibility": {
                    "$ref": "#/components/schemas/Visibility"
                  },
                  "every": {
                    "type": "integer"
                  },
                  "readers": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "boolean"
                    }
                  },
                  "paused": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Connection"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "operationId": "deleteConnection",
        "summary": "Remove a connection and what it brought in",
        "tags": [
          "Connections"
        ],
        "x-zvena-scope": "write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The connection's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/connections/{id}/{step}": {
      "post": {
        "operationId": "connectionStep",
        "summary": "A connection's next step: access, signin, try, connect, sync",
        "tags": [
          "Connections"
        ],
        "x-zvena-scope": "write",
        "description": "access { key | user, password | site } — kept sealed, never shown again; signin — a new sign-in link; try — each list read once on the person's account (reads only); connect { visibility, readers, every } — it syncs from now on; sync — a pass now.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The connection's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "step",
            "in": "path",
            "required": true,
            "description": "access | signin | try | connect | sync",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string"
                  },
                  "user": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  },
                  "site": {
                    "type": "string"
                  },
                  "visibility": {
                    "$ref": "#/components/schemas/Visibility"
                  },
                  "readers": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "boolean"
                    }
                  },
                  "every": {
                    "type": "integer",
                    "minimum": 5,
                    "maximum": 1440
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/eco/agents": {
      "get": {
        "operationId": "listAgents",
        "summary": "Your Airsurf Link agents (services on your machine or network)",
        "tags": [
          "Connections"
        ],
        "x-zvena-scope": "read",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "results",
                    "next_cursor",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Where the next page starts (start_cursor / after); null: no cursor for this list"
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "More follows: read on with next_cursor, or (lists without a cursor) the list was cut at page_size"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      },
      "post": {
        "operationId": "createAgent",
        "summary": "A new Airsurf Link: its token and the command that starts it (shown once)",
        "tags": [
          "Connections"
        ],
        "x-zvena-scope": "write",
        "description": "Run the command next to the service (a computer, a server in the office): it connects out to Airsurf, no port to open. Then findService with { q: 'http://localhost:8080', link: <id> }.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ]
      }
    },
    "/v1/eco/agents/{id}": {
      "delete": {
        "operationId": "deleteAgent",
        "summary": "Remove an Airsurf Link",
        "tags": [
          "Connections"
        ],
        "x-zvena-scope": "write",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The Link's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ZvenaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Zvena-Version": {
                "$ref": "#/components/headers/ZvenaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Restricted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "webhooks": {
    "task.created": {
      "post": {
        "operationId": "webhook_task_created",
        "summary": "task.created, POSTed to a webhook's https address",
        "description": "Check Zvena-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the webhook's signing secret> in constant time, and turn away a t more than five minutes off. After a new secret, two v1 values come for a day (the new one first). Answer any 2xx within 10 s; otherwise the delivery is tried again after 1 min, 5 min, 30 min, 2 h, 6 h (six tries in all). Twenty failed tries in a row turn the webhook off. Zvena-Delivery names the delivery; the body's id the event.",
        "parameters": [
          {
            "name": "Zvena-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Webhook",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Attempt",
            "in": "header",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookDelivery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges it"
          }
        }
      }
    },
    "task.updated": {
      "post": {
        "operationId": "webhook_task_updated",
        "summary": "task.updated, POSTed to a webhook's https address",
        "description": "Check Zvena-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the webhook's signing secret> in constant time, and turn away a t more than five minutes off. After a new secret, two v1 values come for a day (the new one first). Answer any 2xx within 10 s; otherwise the delivery is tried again after 1 min, 5 min, 30 min, 2 h, 6 h (six tries in all). Twenty failed tries in a row turn the webhook off. Zvena-Delivery names the delivery; the body's id the event.",
        "parameters": [
          {
            "name": "Zvena-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Webhook",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Attempt",
            "in": "header",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookDelivery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges it"
          }
        }
      }
    },
    "task.deleted": {
      "post": {
        "operationId": "webhook_task_deleted",
        "summary": "task.deleted, POSTed to a webhook's https address",
        "description": "Check Zvena-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the webhook's signing secret> in constant time, and turn away a t more than five minutes off. After a new secret, two v1 values come for a day (the new one first). Answer any 2xx within 10 s; otherwise the delivery is tried again after 1 min, 5 min, 30 min, 2 h, 6 h (six tries in all). Twenty failed tries in a row turn the webhook off. Zvena-Delivery names the delivery; the body's id the event.",
        "parameters": [
          {
            "name": "Zvena-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Webhook",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Attempt",
            "in": "header",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookDelivery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges it"
          }
        }
      }
    },
    "task.commented": {
      "post": {
        "operationId": "webhook_task_commented",
        "summary": "task.commented, POSTed to a webhook's https address",
        "description": "Check Zvena-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the webhook's signing secret> in constant time, and turn away a t more than five minutes off. After a new secret, two v1 values come for a day (the new one first). Answer any 2xx within 10 s; otherwise the delivery is tried again after 1 min, 5 min, 30 min, 2 h, 6 h (six tries in all). Twenty failed tries in a row turn the webhook off. Zvena-Delivery names the delivery; the body's id the event.",
        "parameters": [
          {
            "name": "Zvena-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Webhook",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Attempt",
            "in": "header",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookDelivery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges it"
          }
        }
      }
    },
    "page.updated": {
      "post": {
        "operationId": "webhook_page_updated",
        "summary": "page.updated, POSTed to a webhook's https address",
        "description": "Check Zvena-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the webhook's signing secret> in constant time, and turn away a t more than five minutes off. After a new secret, two v1 values come for a day (the new one first). Answer any 2xx within 10 s; otherwise the delivery is tried again after 1 min, 5 min, 30 min, 2 h, 6 h (six tries in all). Twenty failed tries in a row turn the webhook off. Zvena-Delivery names the delivery; the body's id the event.",
        "parameters": [
          {
            "name": "Zvena-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Webhook",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Attempt",
            "in": "header",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookDelivery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges it"
          }
        }
      }
    },
    "comment.added": {
      "post": {
        "operationId": "webhook_comment_added",
        "summary": "comment.added, POSTed to a webhook's https address",
        "description": "Check Zvena-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the webhook's signing secret> in constant time, and turn away a t more than five minutes off. After a new secret, two v1 values come for a day (the new one first). Answer any 2xx within 10 s; otherwise the delivery is tried again after 1 min, 5 min, 30 min, 2 h, 6 h (six tries in all). Twenty failed tries in a row turn the webhook off. Zvena-Delivery names the delivery; the body's id the event.",
        "parameters": [
          {
            "name": "Zvena-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Webhook",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Attempt",
            "in": "header",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookDelivery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges it"
          }
        }
      }
    },
    "ping": {
      "post": {
        "operationId": "webhook_ping",
        "summary": "ping, POSTed to a webhook's https address",
        "description": "Check Zvena-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the webhook's signing secret> in constant time, and turn away a t more than five minutes off. After a new secret, two v1 values come for a day (the new one first). Answer any 2xx within 10 s; otherwise the delivery is tried again after 1 min, 5 min, 30 min, 2 h, 6 h (six tries in all). Twenty failed tries in a row turn the webhook off. Zvena-Delivery names the delivery; the body's id the event.",
        "parameters": [
          {
            "name": "Zvena-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Webhook",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Zvena-Attempt",
            "in": "header",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookDelivery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges it"
          }
        }
      }
    },
    "ecosystemEvent": {
      "post": {
        "operationId": "ecosystemEvent",
        "summary": "An ecosystem event, POSTed to the integration's https webhook",
        "description": "Check X-Zvena-Signature-V2 = sha256=<hex HMAC-SHA256 of \"<X-Zvena-Timestamp>.<raw body>\" with the signing secret> and turn away timestamps more than 5 minutes off. X-Zvena-Signature (HMAC of the body alone) is sent too. Deliveries can repeat: the event's id is the same each time (X-Zvena-Delivery is new per delivery).",
        "parameters": [
          {
            "name": "X-Zvena-Event",
            "in": "header",
            "required": true,
            "description": "The event's type",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Zvena-Delivery",
            "in": "header",
            "required": true,
            "description": "This delivery's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Zvena-Timestamp",
            "in": "header",
            "required": true,
            "description": "Unix seconds when it was sent",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Zvena-Signature-V2",
            "in": "header",
            "required": true,
            "description": "sha256=<hex HMAC of \"<timestamp>.<body>\">",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Zvena-Signature",
            "in": "header",
            "required": true,
            "description": "sha256=<hex HMAC of the body>",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges it; otherwise it is sent again after 10 s, 1 min, 5 min, 30 min, 2 h, 6 h and 12 h (about a day), across restarts. The feed (GET /v1/eco/events) keeps the same events a week"
          }
        }
      }
    },
    "run": {
      "post": {
        "operationId": "run",
        "summary": "A run of one of your actions, POSTed to the action's url",
        "description": "Signed like events, with your app's action signing secret (PUT /v1/eco/app): check X-Zvena-Signature-V2 and the timestamp. Idempotency-Key is the run's id: do the action once per id. Answer 2xx when done (optionally { \"result\": {…}, \"object\": {external_id, title, …} }: the object becomes yours, linked to what started the run), 202 to report later (POST /v1/eco/runs/{id}), 4xx when it cannot be done (the message in { \"error\": { \"message\" } } is shown). No answer, 408, 429 or 5xx: sent again after 5 s, 30 s and 2 min.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "The run's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Zvena-Run",
            "in": "header",
            "required": true,
            "description": "The run's id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Zvena-Action",
            "in": "header",
            "required": true,
            "description": "The action's name",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Zvena-Timestamp",
            "in": "header",
            "required": true,
            "description": "Unix seconds when it was sent",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Zvena-Signature-V2",
            "in": "header",
            "required": true,
            "description": "sha256=<hex HMAC of \"<timestamp>.<body>\">",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Zvena-Signature",
            "in": "header",
            "required": true,
            "description": "sha256=<hex HMAC of the body>",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Run"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done"
          },
          "202": {
            "description": "Taken; reported later"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key (zv_secret_…) from Settings → API, or an OAuth access token an app was granted"
      }
    },
    "parameters": {
      "ZvenaVersion": {
        "name": "Zvena-Version",
        "in": "header",
        "required": false,
        "description": "The API version the client expects (2026-10-22); another answers 400",
        "schema": {
          "type": "string",
          "enum": [
            "2026-10-22"
          ]
        }
      },
      "IfMatch": {
        "name": "If-Match",
        "in": "header",
        "required": false,
        "description": "The ETag of your last read: the write happens only if it is still that (412 precondition_failed otherwise)",
        "schema": {
          "type": "string"
        }
      },
      "IfNoneMatch": {
        "name": "If-None-Match",
        "in": "header",
        "required": false,
        "description": "*: create only (412 if it exists)",
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Any unique string (a UUID): sending the same request again within a day returns the first answer (Idempotent-Replayed: true) instead of doing it twice",
        "schema": {
          "type": "string",
          "maxLength": 255
        }
      }
    },
    "headers": {
      "RequestId": {
        "description": "This request's id",
        "schema": {
          "type": "string"
        }
      },
      "RateLimitLimit": {
        "description": "Requests a burst may hold (refills at 10 a second)",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitRemaining": {
        "description": "Requests left in the burst now",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitReset": {
        "description": "Seconds until the burst is full again",
        "schema": {
          "type": "integer"
        }
      },
      "ZvenaVersion": {
        "description": "The API version that answered",
        "schema": {
          "type": "string"
        }
      },
      "RetryAfter": {
        "description": "Seconds to wait",
        "schema": {
          "type": "integer"
        }
      }
    },
    "schemas": {
      "Manifest": {
        "type": "object",
        "description": "What your app is. Names of object types, events and actions: lower-case letters, digits, '.', '_' or '-'.",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "description": {
            "type": "string",
            "maxLength": 300
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Your app's home (https)"
          },
          "icon": {
            "type": "string",
            "maxLength": 16,
            "description": "An emoji or a few letters"
          },
          "objects": {
            "type": "object",
            "maxProperties": 30,
            "propertyNames": {
              "pattern": "^[a-z][a-z0-9_.-]{0,63}$"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "fields": {
                  "type": "object",
                  "maxProperties": 30,
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "enum": [
                          "string",
                          "number",
                          "boolean",
                          "date"
                        ],
                        "default": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "personal": {
                        "type": "boolean",
                        "description": "It names or reaches a person (an e-mail, a customer's name): never sent to the decision model"
                      }
                    }
                  }
                }
              }
            }
          },
          "events": {
            "type": "object",
            "maxProperties": 50,
            "propertyNames": {
              "pattern": "^[a-z][a-z0-9_.-]{0,63}$"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "object": {
                  "type": "string",
                  "description": "One of your object types"
                },
                "fields": {
                  "type": "object",
                  "maxProperties": 30,
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "enum": [
                          "string",
                          "number",
                          "boolean",
                          "date"
                        ],
                        "default": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "personal": {
                        "type": "boolean",
                        "description": "It names or reaches a person (an e-mail, a customer's name): never sent to the decision model"
                      }
                    }
                  }
                }
              }
            }
          },
          "actions": {
            "type": "object",
            "maxProperties": 50,
            "propertyNames": {
              "pattern": "^[a-z][a-z0-9_.-]{0,63}$"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string",
                  "maxLength": 300
                },
                "input": {
                  "type": "object",
                  "maxProperties": 20,
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "enum": [
                          "string",
                          "number",
                          "boolean",
                          "date"
                        ],
                        "default": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "required": {
                        "type": "boolean"
                      },
                      "enum": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "maxItems": 50
                      }
                    }
                  }
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Where runs are POSTed (https, default port). Without it your app collects its runs (GET /v1/eco/runs?claim=1)"
                },
                "undoable": {
                  "type": "boolean",
                  "description": "Your app can take it back (shown before a person confirms)"
                }
              }
            }
          }
        }
      },
      "App": {
        "type": "object",
        "required": [
          "object",
          "id",
          "name",
          "icon",
          "description",
          "url",
          "objects",
          "events",
          "actions",
          "has_manifest"
        ],
        "properties": {
          "object": {
            "const": "app"
          },
          "id": {
            "type": "string",
            "description": "Its integration id"
          },
          "name": {
            "type": "string"
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ]
          },
          "objects": {
            "type": "object"
          },
          "events": {
            "type": "object"
          },
          "actions": {
            "type": "object",
            "description": "Each with title, description, input, undoable and delivery (push | pull); your own app's also with url"
          },
          "has_manifest": {
            "type": "boolean"
          }
        }
      },
      "AppEvent": {
        "type": "object",
        "required": [
          "object",
          "id",
          "type",
          "object_id",
          "data",
          "timestamp"
        ],
        "properties": {
          "object": {
            "const": "app_event"
          },
          "id": {
            "type": "string",
            "description": "evt_…"
          },
          "type": {
            "type": "string"
          },
          "object_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "ext:<id>"
          },
          "data": {
            "type": "object"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Run": {
        "type": "object",
        "description": "An action asked of an app.",
        "required": [
          "object",
          "id",
          "action",
          "input",
          "state",
          "workspace_id",
          "app_id",
          "requested_by",
          "subject",
          "result",
          "error",
          "object_id",
          "attempts",
          "created_time",
          "last_edited_time"
        ],
        "properties": {
          "object": {
            "const": "run"
          },
          "id": {
            "type": "string",
            "description": "run_…: also the Idempotency-Key it is sent with"
          },
          "action": {
            "type": "string"
          },
          "input": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean",
                "null"
              ]
            }
          },
          "state": {
            "enum": [
              "queued",
              "sent",
              "claimed",
              "succeeded",
              "failed",
              "canceled"
            ]
          },
          "workspace_id": {
            "type": "string"
          },
          "app_id": {
            "type": "string",
            "description": "The app it is asked of"
          },
          "requested_by": {
            "type": "object",
            "properties": {
              "type": {
                "enum": [
                  "person",
                  "rule",
                  "integration"
                ]
              },
              "id": {
                "type": "string"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "subject": {
            "type": [
              "object",
              "null"
            ],
            "description": "What started it, when the app's maker may see it",
            "properties": {
              "ref": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "result": {
            "type": [
              "object",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "object_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "ext:<id> of the object the app answered with"
          },
          "attempts": {
            "type": "integer"
          },
          "created_time": {
            "type": "string",
            "format": "date-time"
          },
          "last_edited_time": {
            "type": "string",
            "format": "date-time"
          },
          "attempt_number": {
            "type": "integer",
            "description": "Pushed runs: 1 on the first try"
          }
        }
      },
      "Visibility": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "mode"
            ],
            "properties": {
              "mode": {
                "const": "me"
              }
            },
            "description": "Only whoever connected it (the default)"
          },
          {
            "type": "object",
            "required": [
              "mode"
            ],
            "properties": {
              "mode": {
                "const": "space"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "mode",
              "ids"
            ],
            "properties": {
              "mode": {
                "const": "teams"
              },
              "ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          {
            "type": "object",
            "required": [
              "mode",
              "ids"
            ],
            "properties": {
              "mode": {
                "const": "people"
              },
              "ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        ]
      },
      "FoundService": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "For createConnection (kept 30 minutes)"
          },
          "name": {
            "type": "string"
          },
          "key": {
            "type": "string",
            "description": "The service's host"
          },
          "home": {
            "type": "string"
          },
          "site": {
            "type": "string"
          },
          "ways": {
            "type": "array",
            "items": {
              "enum": [
                "registry",
                "mcp",
                "oauth",
                "spec",
                "key",
                "basic",
                "docs",
                "hook",
                "link"
              ]
            },
            "description": "Best first"
          },
          "oneClick": {
            "type": "boolean"
          }
        }
      },
      "Connection": {
        "type": "object",
        "properties": {
          "object": {
            "const": "connection"
          },
          "id": {
            "type": "string",
            "description": "Also its app's integration id: its actions run with POST /apps/{id}/actions/{action}"
          },
          "name": {
            "type": "string"
          },
          "service": {
            "type": "string"
          },
          "state": {
            "enum": [
              "draft",
              "signin",
              "ready",
              "paused",
              "error"
            ]
          },
          "visibility": {
            "$ref": "#/components/schemas/Visibility"
          },
          "every": {
            "type": "integer",
            "description": "Minutes between syncs"
          },
          "items": {
            "type": "integer"
          },
          "readers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "on": {
                  "type": "boolean"
                },
                "count": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              }
            }
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "reads": {
                  "type": "boolean"
                }
              }
            }
          },
          "next": {
            "type": [
              "object",
              "null"
            ],
            "description": "What it needs next, while not connected"
          }
        }
      },
      "RuleInput": {
        "type": "object",
        "required": [
          "when",
          "then"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 200
          },
          "on": {
            "type": "boolean",
            "default": true
          },
          "when": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "type",
                  "app"
                ],
                "properties": {
                  "type": {
                    "const": "app"
                  },
                  "app": {
                    "type": "string",
                    "description": "An app's integration id"
                  },
                  "on": {
                    "enum": [
                      "object",
                      "event"
                    ],
                    "default": "object"
                  },
                  "objectType": {
                    "type": "string",
                    "description": "on object: only this type"
                  },
                  "event": {
                    "type": "string",
                    "description": "on event: only this event"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "type",
                  "entity"
                ],
                "properties": {
                  "type": {
                    "const": "projects"
                  },
                  "entity": {
                    "const": "issue"
                  },
                  "project": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "type",
                  "db"
                ],
                "properties": {
                  "type": {
                    "const": "notes"
                  },
                  "db": {
                    "type": "string",
                    "description": "A Docs database's id"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "type",
                  "key"
                ],
                "properties": {
                  "type": {
                    "const": "metric"
                  },
                  "key": {
                    "type": "string"
                  }
                }
              }
            ]
          },
          "if": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "kind"
                ],
                "properties": {
                  "kind": {
                    "const": "always"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "kind",
                  "field",
                  "op",
                  "value"
                ],
                "properties": {
                  "kind": {
                    "const": "compare"
                  },
                  "field": {
                    "type": "string",
                    "description": "A fact: title, status, status_category, due, url, a property or event data key"
                  },
                  "op": {
                    "enum": [
                      ">=",
                      ">",
                      "<=",
                      "<",
                      "=",
                      "!="
                    ]
                  },
                  "value": {
                    "type": [
                      "string",
                      "number",
                      "boolean"
                    ]
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "kind",
                  "question",
                  "fields"
                ],
                "properties": {
                  "kind": {
                    "const": "ask"
                  },
                  "question": {
                    "type": "string",
                    "description": "A yes/no question about the fields"
                  },
                  "fields": {
                    "type": "array",
                    "maxItems": 12,
                    "items": {
                      "type": "string"
                    },
                    "description": "The only facts sent (never personal ones)"
                  },
                  "auto": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "default": 0.9
                  },
                  "suggest": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "default": 0.6
                  }
                }
              }
            ]
          },
          "then": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "oneOf": [
                {
                  "type": "object",
                  "required": [
                    "do",
                    "app",
                    "action"
                  ],
                  "properties": {
                    "do": {
                      "const": "app.run"
                    },
                    "app": {
                      "type": "string",
                      "description": "An app's integration id"
                    },
                    "action": {
                      "type": "string"
                    },
                    "input": {
                      "type": "object",
                      "description": "\"{fact}\" in a value takes it from the subject: \"{amount}\", \"Invoice for {title}\"",
                      "additionalProperties": {
                        "type": [
                          "string",
                          "number",
                          "boolean",
                          "null"
                        ]
                      }
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "do",
                    "title"
                  ],
                  "properties": {
                    "do": {
                      "const": "issue.create"
                    },
                    "title": {
                      "type": "string",
                      "description": "\"{title}\" takes the subject's fact"
                    },
                    "teamId": {
                      "type": "string"
                    },
                    "projectId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "do",
                    "issue"
                  ],
                  "properties": {
                    "do": {
                      "enum": [
                        "issue.done",
                        "issue.set"
                      ]
                    },
                    "issue": {
                      "type": "string",
                      "description": "\"$subject\" or an id"
                    },
                    "field": {
                      "enum": [
                        "status",
                        "priority",
                        "assignee",
                        "due"
                      ]
                    },
                    "value": {}
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "do",
                    "from"
                  ],
                  "properties": {
                    "do": {
                      "const": "links.done"
                    },
                    "from": {
                      "type": "string",
                      "description": "\"$subject\" or a ref"
                    },
                    "kinds": {
                      "type": "array",
                      "items": {
                        "enum": [
                          "note",
                          "issue"
                        ]
                      }
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "Rule": {
        "type": "object",
        "required": [
          "object",
          "id",
          "name",
          "on",
          "when",
          "if",
          "then",
          "apps"
        ],
        "properties": {
          "object": {
            "const": "rule"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "on": {
            "type": "boolean"
          },
          "when": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "type",
                  "app"
                ],
                "properties": {
                  "type": {
                    "const": "app"
                  },
                  "app": {
                    "type": "string",
                    "description": "An app's integration id"
                  },
                  "on": {
                    "enum": [
                      "object",
                      "event"
                    ],
                    "default": "object"
                  },
                  "objectType": {
                    "type": "string",
                    "description": "on object: only this type"
                  },
                  "event": {
                    "type": "string",
                    "description": "on event: only this event"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "type",
                  "entity"
                ],
                "properties": {
                  "type": {
                    "const": "projects"
                  },
                  "entity": {
                    "const": "issue"
                  },
                  "project": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "type",
                  "db"
                ],
                "properties": {
                  "type": {
                    "const": "notes"
                  },
                  "db": {
                    "type": "string",
                    "description": "A Docs database's id"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "type",
                  "key"
                ],
                "properties": {
                  "type": {
                    "const": "metric"
                  },
                  "key": {
                    "type": "string"
                  }
                }
              }
            ]
          },
          "if": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "kind"
                ],
                "properties": {
                  "kind": {
                    "const": "always"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "kind",
                  "field",
                  "op",
                  "value"
                ],
                "properties": {
                  "kind": {
                    "const": "compare"
                  },
                  "field": {
                    "type": "string",
                    "description": "A fact: title, status, status_category, due, url, a property or event data key"
                  },
                  "op": {
                    "enum": [
                      ">=",
                      ">",
                      "<=",
                      "<",
                      "=",
                      "!="
                    ]
                  },
                  "value": {
                    "type": [
                      "string",
                      "number",
                      "boolean"
                    ]
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "kind",
                  "question",
                  "fields"
                ],
                "properties": {
                  "kind": {
                    "const": "ask"
                  },
                  "question": {
                    "type": "string",
                    "description": "A yes/no question about the fields"
                  },
                  "fields": {
                    "type": "array",
                    "maxItems": 12,
                    "items": {
                      "type": "string"
                    },
                    "description": "The only facts sent (never personal ones)"
                  },
                  "auto": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "default": 0.9
                  },
                  "suggest": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "default": 0.6
                  }
                }
              }
            ]
          },
          "then": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "object",
                  "required": [
                    "do",
                    "app",
                    "action"
                  ],
                  "properties": {
                    "do": {
                      "const": "app.run"
                    },
                    "app": {
                      "type": "string",
                      "description": "An app's integration id"
                    },
                    "action": {
                      "type": "string"
                    },
                    "input": {
                      "type": "object",
                      "description": "\"{fact}\" in a value takes it from the subject: \"{amount}\", \"Invoice for {title}\"",
                      "additionalProperties": {
                        "type": [
                          "string",
                          "number",
                          "boolean",
                          "null"
                        ]
                      }
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "do",
                    "title"
                  ],
                  "properties": {
                    "do": {
                      "const": "issue.create"
                    },
                    "title": {
                      "type": "string",
                      "description": "\"{title}\" takes the subject's fact"
                    },
                    "teamId": {
                      "type": "string"
                    },
                    "projectId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "do",
                    "issue"
                  ],
                  "properties": {
                    "do": {
                      "enum": [
                        "issue.done",
                        "issue.set"
                      ]
                    },
                    "issue": {
                      "type": "string",
                      "description": "\"$subject\" or an id"
                    },
                    "field": {
                      "enum": [
                        "status",
                        "priority",
                        "assignee",
                        "due"
                      ]
                    },
                    "value": {}
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "do",
                    "from"
                  ],
                  "properties": {
                    "do": {
                      "const": "links.done"
                    },
                    "from": {
                      "type": "string",
                      "description": "\"$subject\" or a ref"
                    },
                    "kinds": {
                      "type": "array",
                      "items": {
                        "enum": [
                          "note",
                          "issue"
                        ]
                      }
                    }
                  }
                }
              ]
            }
          },
          "apps": {
            "enum": [
              "confirm",
              "auto",
              null
            ],
            "description": "confirm: each run waits for a person's yes in Airsurf; auto: the owner let it act by itself"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "object",
          "status",
          "code",
          "message",
          "request_id"
        ],
        "properties": {
          "object": {
            "const": "error"
          },
          "status": {
            "type": "integer"
          },
          "code": {
            "enum": [
              "invalid_json",
              "validation_error",
              "unauthorized",
              "restricted_resource",
              "object_not_found",
              "invalid_request_url",
              "method_not_allowed",
              "conflict_error",
              "precondition_failed",
              "cursor_expired",
              "rate_limited",
              "internal_server_error"
            ]
          },
          "message": {
            "type": "string"
          },
          "request_id": {
            "type": "string",
            "description": "X-Request-Id of the request: name it to support"
          },
          "retry_after": {
            "type": "integer",
            "description": "rate_limited: seconds to wait"
          }
        }
      },
      "StatusCategory": {
        "enum": [
          "backlog",
          "unstarted",
          "started",
          "completed",
          "canceled"
        ]
      },
      "Card": {
        "type": "object",
        "description": "What a person sees of an object, whichever product it is from. Every field is there; null when the object has none.",
        "required": [
          "object",
          "ref",
          "kind",
          "title",
          "url",
          "icon",
          "color",
          "subtitle",
          "status",
          "assignee",
          "due",
          "priority",
          "progress",
          "source",
          "ext_type",
          "last_edited_time"
        ],
        "properties": {
          "object": {
            "const": "card"
          },
          "ref": {
            "type": "string",
            "description": "A ref: note:<id> (a Docs page or row), issue:<id>, project:<id>, design:<file>[/<frame>], event:<id>, user:<id> or ext:<id> (another app's object)."
          },
          "kind": {
            "enum": [
              "note",
              "issue",
              "project",
              "design",
              "user",
              "event",
              "ext",
              "metric"
            ]
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Where it opens in Airsurf"
          },
          "icon": {
            "type": [
              "string",
              "null"
            ],
            "description": "An emoji"
          },
          "color": {
            "type": [
              "string",
              "null"
            ]
          },
          "subtitle": {
            "type": [
              "string",
              "null"
            ],
            "description": "The second line: an issue's KEY-12, a page's parent, an object's source and status"
          },
          "status": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "name",
                  "color",
                  "category"
                ],
                "properties": {
                  "id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Issues: the status's id"
                  },
                  "name": {
                    "type": "string"
                  },
                  "color": {
                    "type": "string"
                  },
                  "category": {
                    "$ref": "#/components/schemas/StatusCategory"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "assignee": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "null: a name from another app"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "due": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "priority": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 4,
            "description": "Issues: 0 none, 1 urgent … 4 low"
          },
          "progress": {
            "type": [
              "number",
              "null"
            ],
            "description": "Projects: share of completed issues, 0–1"
          },
          "source": {
            "type": [
              "string",
              "null"
            ],
            "description": "External objects: the integration that keeps it"
          },
          "ext_type": {
            "type": [
              "string",
              "null"
            ],
            "description": "External objects: their type"
          },
          "last_edited_time": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "snippet": {
            "type": "string",
            "description": "Search: the words around the match"
          }
        }
      },
      "Resolution": {
        "type": "object",
        "required": [
          "object",
          "input",
          "ref",
          "card"
        ],
        "properties": {
          "object": {
            "const": "resolution"
          },
          "input": {
            "type": "string"
          },
          "ref": {
            "type": [
              "string",
              "null"
            ],
            "description": "null: it names nothing the maker may see"
          },
          "card": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Card"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Related": {
        "type": "object",
        "required": [
          "object",
          "ref",
          "via",
          "direction",
          "manual",
          "smart",
          "card"
        ],
        "properties": {
          "object": {
            "const": "related"
          },
          "ref": {
            "type": "string"
          },
          "via": {
            "enum": [
              "mention",
              "link",
              "embed",
              "relation",
              "converted",
              "manual",
              "smart"
            ]
          },
          "direction": {
            "enum": [
              "out",
              "in"
            ]
          },
          "manual": {
            "type": "boolean"
          },
          "smart": {
            "type": "boolean",
            "description": "Airsurf linked them by itself (smart links)"
          },
          "card": {
            "$ref": "#/components/schemas/Card"
          }
        }
      },
      "Suggestion": {
        "type": "object",
        "required": [
          "object",
          "id",
          "ref",
          "confidence",
          "card"
        ],
        "properties": {
          "object": {
            "const": "suggestion"
          },
          "id": {
            "type": "string"
          },
          "ref": {
            "type": "string"
          },
          "confidence": {
            "type": [
              "number",
              "null"
            ],
            "description": "How sure the model is, 0–1; null: they share a reference and the model was not asked"
          },
          "card": {
            "$ref": "#/components/schemas/Card"
          }
        }
      },
      "Link": {
        "type": "object",
        "required": [
          "object",
          "src",
          "dst",
          "via",
          "direction",
          "part",
          "created_time"
        ],
        "properties": {
          "object": {
            "const": "link"
          },
          "src": {
            "type": "string"
          },
          "dst": {
            "type": "string"
          },
          "via": {
            "enum": [
              "mention",
              "link",
              "embed",
              "relation",
              "converted",
              "manual",
              "smart"
            ]
          },
          "direction": {
            "enum": [
              "out",
              "in"
            ]
          },
          "part": {
            "type": [
              "string",
              "null"
            ],
            "description": "Which part of src makes it (a property, a block); null: the whole"
          },
          "created_time": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Team": {
        "type": "object",
        "required": [
          "object",
          "id",
          "key",
          "name",
          "color",
          "private"
        ],
        "properties": {
          "object": {
            "const": "team"
          },
          "id": {
            "type": "string"
          },
          "key": {
            "type": "string",
            "description": "Its issues' prefix (ENG)"
          },
          "name": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "private": {
            "type": "boolean"
          }
        }
      },
      "Project": {
        "type": "object",
        "required": [
          "object",
          "ref",
          "id",
          "name",
          "icon",
          "color"
        ],
        "properties": {
          "object": {
            "const": "project"
          },
          "ref": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          },
          "color": {
            "type": "string"
          }
        }
      },
      "Status": {
        "type": "object",
        "required": [
          "object",
          "id",
          "name",
          "color",
          "category"
        ],
        "properties": {
          "object": {
            "const": "status"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "category": {
            "$ref": "#/components/schemas/StatusCategory"
          }
        }
      },
      "IssueInput": {
        "type": "object",
        "properties": {
          "team_id": {
            "type": "string",
            "description": "Required to file an issue (GET /v1/eco/teams)"
          },
          "title": {
            "type": "string",
            "maxLength": 300
          },
          "description": {
            "type": "string",
            "description": "Markdown"
          },
          "status_id": {
            "type": "string",
            "description": "GET /v1/eco/issues/{id}/statuses"
          },
          "priority": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4,
            "description": "0 none, 1 urgent … 4 low"
          },
          "assignee_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "A member's user id"
          },
          "project_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "due_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "links": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string"
            },
            "description": "Refs, Airsurf links, KEY-12 or URLs of other apps' objects to link the issue with (by hand)"
          }
        }
      },
      "IssueWritten": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Card"
          },
          {
            "type": "object",
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The issue's id"
              },
              "identifier": {
                "type": "string",
                "description": "ENG-12 (on creation)"
              },
              "links": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The refs linked, when links was sent"
              }
            }
          }
        ]
      },
      "Issue": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Card"
          },
          {
            "type": "object",
            "required": [
              "id",
              "identifier",
              "description",
              "priority",
              "status_id",
              "team",
              "created_time",
              "last_edited_time"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "identifier": {
                "type": "string",
                "description": "ENG-12"
              },
              "description": {
                "type": "string",
                "description": "Markdown"
              },
              "estimate": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "status_id": {
                "type": "string"
              },
              "assignee_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "creator_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "project_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "parent_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "due_date": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date"
              },
              "label_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "team": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "key": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  }
                }
              },
              "created_time": {
                "type": "string",
                "format": "date-time"
              },
              "last_edited_time": {
                "type": "string",
                "format": "date-time"
              },
              "started_time": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "completed_time": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "canceled_time": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "archived_time": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          }
        ]
      },
      "ExternalObjectInput": {
        "type": "object",
        "required": [
          "title"
        ],
        "description": "PUT replaces the object: fields left out are cleared.",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300
          },
          "type": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$",
            "examples": [
              "github.pull_request",
              "hubspot.deal"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "pattern": "^https?://",
            "description": "Where it opens in your app; links to it pasted in Airsurf resolve to this object"
          },
          "icon": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 16,
            "description": "An emoji or a few letters"
          },
          "status": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "string",
                "maxLength": 60
              },
              {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 60
                  },
                  "category": {
                    "$ref": "#/components/schemas/StatusCategory"
                  },
                  "color": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$"
                  }
                }
              }
            ]
          },
          "assignee": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 120,
            "description": "A name, as your app shows it"
          },
          "due": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "properties": {
            "type": "object",
            "maxProperties": 30,
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean",
                "null"
              ]
            }
          },
          "text": {
            "type": "string",
            "description": "Searchable text (beyond 20,000 characters it is cut); KEY-12, @mentions and Airsurf links in it become links"
          },
          "links": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string"
            },
            "description": "What the object is about: refs, Airsurf links, KEY-12, URLs of other objects"
          },
          "version": {
            "type": [
              "number",
              "string",
              "null"
            ],
            "description": "Its version in your app: a number that grows, or a date-time (its updated_at). A write with a lower version than the kept one changes nothing (409, stale: true)"
          }
        }
      },
      "ExternalObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "external_id",
          "type",
          "title",
          "url",
          "icon",
          "status",
          "assignee",
          "due",
          "properties",
          "links",
          "integration_id",
          "version",
          "created_time",
          "last_edited_time",
          "app_url"
        ],
        "properties": {
          "object": {
            "const": "external_object"
          },
          "id": {
            "type": "string",
            "description": "Its ref (ext:<id>)"
          },
          "external_id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": [
              "string",
              "null"
            ]
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "name",
                  "color",
                  "category"
                ],
                "properties": {
                  "id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Issues: the status's id"
                  },
                  "name": {
                    "type": "string"
                  },
                  "color": {
                    "type": "string"
                  },
                  "category": {
                    "$ref": "#/components/schemas/StatusCategory"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "assignee": {
            "type": [
              "string",
              "null"
            ]
          },
          "due": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "properties": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean",
                "null"
              ]
            }
          },
          "links": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The refs it links to (as sent and as found in its text), resolved"
          },
          "integration_id": {
            "type": "string"
          },
          "version": {
            "type": [
              "number",
              "null"
            ],
            "description": "Its version in your app, as last written (a date-time is kept as its milliseconds)"
          },
          "created_time": {
            "type": "string",
            "format": "date-time"
          },
          "last_edited_time": {
            "type": "string",
            "format": "date-time"
          },
          "app_url": {
            "type": "string",
            "format": "uri",
            "description": "Its address in Airsurf (members of the workspace go on to url)"
          }
        }
      },
      "BatchSaved": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ExternalObject"
          },
          {
            "type": "object",
            "required": [
              "index",
              "status_code"
            ],
            "properties": {
              "index": {
                "type": "integer"
              },
              "status_code": {
                "enum": [
                  200,
                  201
                ]
              }
            }
          }
        ]
      },
      "BatchError": {
        "type": "object",
        "required": [
          "object",
          "index",
          "status_code",
          "code",
          "message"
        ],
        "properties": {
          "object": {
            "const": "error"
          },
          "index": {
            "type": "integer"
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "integer"
          },
          "status_code": {
            "enum": [
              400,
              409
            ]
          },
          "code": {
            "enum": [
              "validation_error",
              "conflict_error"
            ]
          },
          "stale": {
            "type": "boolean",
            "description": "Older than the version kept: nothing changed"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Event": {
        "type": "object",
        "description": "A change, by refs only: read what you need through the API. The same event has the same id in the feed and in a webhook.",
        "required": [
          "object",
          "id",
          "type",
          "timestamp",
          "workspace_id",
          "integration_id",
          "refs",
          "actor",
          "data",
          "seq"
        ],
        "properties": {
          "object": {
            "const": "event"
          },
          "id": {
            "type": "string",
            "description": "evt_<seq>"
          },
          "type": {
            "enum": [
              "document.changed",
              "issue.changed",
              "issue.commented",
              "issue.deleted",
              "project.changed",
              "project.deleted",
              "event.changed",
              "design.changed",
              "links.changed",
              "object.changed",
              "object.deleted",
              "app.event"
            ]
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "workspace_id": {
            "type": "string"
          },
          "integration_id": {
            "type": "string"
          },
          "refs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "actor": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "type": {
                "enum": [
                  "person",
                  "integration",
                  "system"
                ]
              }
            }
          },
          "data": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean",
                "null"
              ]
            },
            "description": "issue.commented: comment_id; object.*: external_id, integration_id"
          },
          "seq": {
            "type": "integer",
            "description": "Its place in the feed"
          },
          "attempt_number": {
            "type": "integer",
            "description": "Webhooks only: 1 on the first try"
          }
        }
      },
      "Me": {
        "type": "object",
        "required": [
          "object",
          "id",
          "name",
          "workspace",
          "plan",
          "acting_as",
          "scopes",
          "webhook",
          "api_version",
          "events_retention_days"
        ],
        "properties": {
          "object": {
            "const": "integration"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "workspace": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "plan": {
            "enum": [
              "free",
              "plus",
              "pro",
              "max",
              "self-hosted"
            ],
            "description": "The workspace's plan on airsurf.app: free, plus, pro or max. \"self-hosted\" only comes from a server without billing (Airsurf's own test servers); Airsurf is offered as a hosted service."
          },
          "acting_as": {
            "type": "object",
            "description": "The person it acts as (who made it)",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "scopes": {
            "type": "object",
            "properties": {
              "read": {
                "type": "boolean"
              },
              "write": {
                "type": "boolean"
              },
              "objects": {
                "type": "boolean"
              },
              "events": {
                "type": "boolean"
              },
              "actions": {
                "type": "boolean"
              },
              "products": {
                "type": "array",
                "items": {
                  "enum": [
                    "docs",
                    "projects",
                    "calendar",
                    "design",
                    "tables",
                    "make"
                  ]
                }
              }
            }
          },
          "webhook": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "url": {
                "type": "string"
              },
              "events": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "api_version": {
            "type": "string"
          },
          "events_retention_days": {
            "type": "integer"
          }
        }
      },
      "TaskStatus": {
        "type": "object",
        "required": [
          "object",
          "id",
          "name",
          "category",
          "color"
        ],
        "properties": {
          "object": {
            "const": "status"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "$ref": "#/components/schemas/StatusCategory"
          },
          "color": {
            "type": "string"
          }
        }
      },
      "TaskTeam": {
        "type": "object",
        "required": [
          "object",
          "id",
          "key",
          "name",
          "description",
          "color",
          "private",
          "triage",
          "statuses"
        ],
        "properties": {
          "object": {
            "const": "team"
          },
          "id": {
            "type": "string"
          },
          "key": {
            "type": "string",
            "description": "Its issues' prefix (ENG)"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "private": {
            "type": "boolean"
          },
          "triage": {
            "type": "boolean"
          },
          "statuses": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/TaskStatus"
                },
                {
                  "type": "object",
                  "required": [
                    "position"
                  ],
                  "properties": {
                    "position": {
                      "type": "number"
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "Person": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "Task": {
        "type": "object",
        "required": [
          "object",
          "id",
          "identifier",
          "number",
          "title",
          "description",
          "url",
          "team",
          "status",
          "priority",
          "priority_label",
          "estimate",
          "assignee",
          "creator",
          "project",
          "cycle_id",
          "parent_id",
          "labels",
          "due_date",
          "branch_name",
          "comment_count",
          "sub_tasks",
          "created_time",
          "last_edited_time",
          "started_time",
          "completed_time",
          "canceled_time",
          "archived_time"
        ],
        "properties": {
          "object": {
            "const": "task"
          },
          "id": {
            "type": "string"
          },
          "identifier": {
            "type": "string",
            "description": "ENG-123"
          },
          "number": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "description": "Markdown (\"\" in lists unless description=true)"
          },
          "url": {
            "type": "string",
            "description": "Its page in Airsurf",
            "format": "uri"
          },
          "team": {
            "type": "object",
            "required": [
              "id",
              "key",
              "name"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "key": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "status": {
            "$ref": "#/components/schemas/TaskStatus"
          },
          "priority": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4,
            "description": "0 none, 1 urgent, 2 high, 3 medium, 4 low"
          },
          "priority_label": {
            "enum": [
              "none",
              "urgent",
              "high",
              "medium",
              "low"
            ]
          },
          "estimate": {
            "type": [
              "number",
              "null"
            ]
          },
          "assignee": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Person"
              },
              {
                "type": "null"
              }
            ]
          },
          "creator": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Person"
              },
              {
                "type": "null"
              }
            ]
          },
          "project": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "id",
                  "name"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "cycle_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "color"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "color": {
                  "type": "string"
                }
              }
            }
          },
          "due_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "YYYY-MM-DD"
          },
          "branch_name": {
            "type": "string",
            "description": "The git branch for the key's maker: <handle>/<ENG-123>-<title>"
          },
          "comment_count": {
            "type": "integer"
          },
          "sub_tasks": {
            "type": "object",
            "required": [
              "total",
              "done"
            ],
            "properties": {
              "total": {
                "type": "integer"
              },
              "done": {
                "type": "integer"
              }
            }
          },
          "created_time": {
            "type": "string",
            "format": "date-time"
          },
          "last_edited_time": {
            "type": "string",
            "format": "date-time"
          },
          "started_time": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "completed_time": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "canceled_time": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "archived_time": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "TaskPatch": {
        "type": "object",
        "required": [],
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "description": "Markdown"
          },
          "status_id": {
            "type": "string",
            "description": "A status of the issue's team (GET /v1/teams)"
          },
          "status_category": {
            "$ref": "#/components/schemas/StatusCategory",
            "description": "Or the team's first status of a category (started: In Progress)"
          },
          "priority": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4
          },
          "assignee_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "A member's id, me, or null"
          },
          "project_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "estimate": {
            "type": [
              "number",
              "null"
            ]
          },
          "due_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "YYYY-MM-DD"
          },
          "label_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 50
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "An issue's id or identifier"
          },
          "archived": {
            "type": "boolean"
          }
        }
      },
      "TaskInput": {
        "allOf": [
          {
            "type": "object",
            "required": [
              "title"
            ],
            "properties": {
              "team_id": {
                "type": "string",
                "description": "The team's id"
              },
              "team": {
                "type": "string",
                "description": "…or its key (ENG)"
              },
              "title": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "properties": {
              "description": {
                "type": "string",
                "description": "Markdown"
              },
              "status_id": {
                "type": "string"
              },
              "status_category": {
                "$ref": "#/components/schemas/StatusCategory"
              },
              "priority": {
                "type": "integer",
                "minimum": 0,
                "maximum": 4
              },
              "assignee_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "project_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "estimate": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "due_date": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "label_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "parent_id": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        ],
        "description": "team_id or team is required"
      },
      "TaskComment": {
        "type": "object",
        "required": [
          "object",
          "id",
          "task_id",
          "parent_id",
          "body",
          "author",
          "created_time",
          "last_edited_time"
        ],
        "properties": {
          "object": {
            "const": "comment"
          },
          "id": {
            "type": "string"
          },
          "task_id": {
            "type": "string"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "body": {
            "type": "string",
            "description": "Markdown"
          },
          "author": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Person"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_time": {
            "type": "string",
            "format": "date-time"
          },
          "last_edited_time": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookEventType": {
        "enum": [
          "task.created",
          "task.updated",
          "task.deleted",
          "task.commented",
          "page.updated",
          "comment.added"
        ]
      },
      "Webhook": {
        "type": "object",
        "required": [
          "object",
          "id",
          "url",
          "label",
          "events",
          "team_id",
          "enabled",
          "disabled_reason",
          "created_time",
          "last_edited_time"
        ],
        "properties": {
          "object": {
            "const": "webhook"
          },
          "id": {
            "type": "string",
            "description": "wh_…"
          },
          "url": {
            "type": "string",
            "description": "https only",
            "format": "uri"
          },
          "label": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            }
          },
          "team_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "null: every team the maker sees"
          },
          "enabled": {
            "type": "boolean"
          },
          "disabled_reason": {
            "enum": [
              "failing",
              "manual",
              null
            ]
          },
          "created_time": {
            "type": "string",
            "format": "date-time"
          },
          "last_edited_time": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookInput": {
        "type": "object",
        "required": [
          "url",
          "events"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "An https address the internet can reach"
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            }
          },
          "team_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "label": {
            "type": "string"
          }
        }
      },
      "WebhookPatch": {
        "type": "object",
        "required": [],
        "properties": {
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            }
          },
          "team_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "label": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "WebhookActor": {
        "type": "object",
        "required": [
          "type",
          "id",
          "name"
        ],
        "properties": {
          "type": {
            "enum": [
              "person",
              "app",
              "automation"
            ]
          },
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "A member's id, an integration's id, or null"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "WebhookDelivery": {
        "type": "object",
        "required": [
          "id",
          "type",
          "created_at",
          "workspace_id",
          "webhook_id",
          "actor",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "evt_…: the event (the same for every webhook, and on a redelivery)"
          },
          "type": {
            "enum": [
              "task.created",
              "task.updated",
              "task.deleted",
              "task.commented",
              "page.updated",
              "comment.added",
              "ping"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "workspace_id": {
            "type": "string"
          },
          "webhook_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "null in airsurf webhooks listen"
          },
          "actor": {
            "$ref": "#/components/schemas/WebhookActor"
          },
          "data": {
            "type": "object",
            "description": "task.*: a Task (task.commented: a TaskComment with its issue; task.deleted: id, title, team); page.updated: a page; comment.added: a page comment"
          },
          "updated_from": {
            "type": "object",
            "description": "task.updated: the fields that changed, with their values before"
          }
        }
      },
      "DocsObject": {
        "type": "object",
        "description": "A Notion-shaped object (page, block, database, data source, user, comment): https://developers.notion.com/reference",
        "additionalProperties": true
      }
    },
    "responses": {
      "Invalid": {
        "description": "validation_error or invalid_json: the request is not right; the message says what",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "unauthorized: the token is not valid",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Restricted": {
        "description": "restricted_resource: a scope or product the integration was not given, its maker may not do this (or no longer edits the workspace, or left it)",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "object_not_found: it is not there, or the integration's maker may not see it",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "conflict_error: the integration keeps the most objects it may, an Idempotency-Key was used with another request, the change conflicts, or (stale: true, with current) a newer version of the object is kept already",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "PreconditionFailed": {
        "description": "precondition_failed: it changed since you read it (If-Match), or it exists (If-None-Match: *); read it again",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "CursorExpired": {
        "description": "cursor_expired: the cursor is older than the feed keeps; read again without after",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooLarge": {
        "description": "validation_error: the body is over 2 MB",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "rate_limited: wait Retry-After seconds",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError": {
        "description": "internal_server_error: name request_id to support",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}
