> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a Cypher query

> Execute an openCypher query (org-scoped, read-only, temporary). Automated and agent callers must send `intent`: one short sentence naming the specific question this query should answer and how the result will guide the next step. It never changes the query or its results; when set, it is attached to the request trace in APM and to the security audit log of rejected queries, so automated traffic has an attributable purpose.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/orgs/{orgSlug}/cypher
openapi: 3.0.3
info:
  title: Tolmo API
  version: 1.0.0
  description: >-
    The Tolmo REST API. Use an organization API key for automation or a CLI user
    token for user-authenticated operations. Most endpoints are scoped to one
    organization.
servers:
  - url: https://api.tolmo.com
    description: Production
security: []
paths:
  /api/v1/orgs/{orgSlug}/cypher:
    post:
      tags:
        - cypher
      summary: Run a Cypher query
      description: >-
        Execute an openCypher query (org-scoped, read-only, temporary).
        Automated and agent callers must send `intent`: one short sentence
        naming the specific question this query should answer and how the result
        will guide the next step. It never changes the query or its results;
        when set, it is attached to the request trace in APM and to the security
        audit log of rejected queries, so automated traffic has an attributable
        purpose.
      parameters:
        - schema:
            type: string
          in: path
          name: orgSlug
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 10000
                parameters:
                  type: object
                  additionalProperties: {}
                intent:
                  description: >-
                    Automated and agent callers MUST set this on every query: in
                    one short sentence, name the specific question this query
                    should answer and how the result will guide your next step.
                    For initial discovery, say what you need to learn, e.g.
                    "Identify which resource types are present so I can choose
                    the right checks for this environment". For a follow-up,
                    e.g. "Find roles attached to exposed EC2 instances so I can
                    inspect their permissions". Avoid generic phrases like
                    "explore the graph", repeating the overall task, or assuming
                    a finding before seeing results. Recorded for observability;
                    does not affect query results. Omit only for a one-off
                    interactive query typed by a human.
                  type: string
                  maxLength: 1000
              required:
                - query
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  rows:
                    type: array
                    items:
                      type: object
                      additionalProperties: {}
                  metadata:
                    type: object
                    properties:
                      executionTimeMs:
                        type: number
                      rowCount:
                        type: number
                    required:
                      - executionTimeMs
                      - rowCount
                    additionalProperties: false
                required:
                  - rows
                  - metadata
                additionalProperties: false
        '412':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '503':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
      security:
        - bearerAuth: []
components:
  schemas:
    HttpError:
      type: object
      properties:
        statusCode:
          type: number
        code:
          type: string
        error:
          type: string
        message:
          type: string
      title: HttpError
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A Tolmo API token, sent as `Authorization: Bearer <token>`. Either a
        user token (`usr_tok.*`, minted by `tolmo auth login`, scoped to your
        own permissions) or an org API token created in the Tolmo app, for CI
        and automation.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.