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

# Post evaluate query

> Query v2: query for any expression.

Unlike `GET /facts`, which only lists facts you've added to Oso Cloud, you can use `POST /evaluate_query` to list derived information about any rule in your policy.



## OpenAPI

````yaml post /evaluate_query
openapi: 3.1.0
info:
  title: Oso Cloud HTTP API
  version: 0.1.0
  description: >-
    <p>Oso Cloud exposes an HTTP API that you can use to make queries directly,
    without using one of the clients.</p><p>For endpoints that require
    authentication, pass your API key as an HTTP Bearer Auth payload.</p><p>For
    example, using curl: <code>curl -H &quot;Authorization: Bearer
    $OSO_AUTH&quot; https://cloud.osohq.com/api/</code></p>
servers:
  - url: https://api.osohq.com/api/
security: []
paths:
  /evaluate_query:
    post:
      tags:
        - Check API
      description: >-
        Query v2: query for any expression.


        Unlike `GET /facts`, which only lists facts you've added to Oso Cloud,
        you can use `POST /evaluate_query` to list derived information about any
        rule in your policy.
      operationId: post_evaluate_query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Query'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - ApiKey: []
      x-codeSamples:
        - lang: javascript
          label: Node.js
          source: >
            import { Oso } from 'oso-cloud';


            const apiKey = process.env.OSO_CLOUD_API_KEY;

            const oso = new Oso("https://cloud.osohq.com", apiKey);


            // Basic query building

            const actor = { type: "User", id: "alice" };

            const repository = { type: "Repository", id: "anvils" };

            const query = oso.buildQuery(["allow", actor, "read", repository]);

            const result = await query.evaluate(repository);


            // Add constraints with 'and'

            const constrainedQuery = oso.buildQuery(["allow", actor, "read",
            repository])
              .and(["has_relation", repository, "folder", { type: "Folder", id: "docs" }]);

            // Different evaluation modes

            const exists = await query.evaluate();                           //
            Boolean

            const actions = await query.evaluate("action");                   //
            Single variable

            const pairs = await query.evaluate(["action", "repository"]);     //
            Tuple variables
        - lang: python
          label: Python
          source: >
            import os

            from oso_cloud import Oso, Value


            oso = Oso(api_key=os.environ.get('OSO_CLOUD_API_KEY', None))


            # Basic query building

            actor = Value("User", "alice")

            repository = Value("Repository", "anvils")

            query = oso.build_query(("allow", actor, "read", repository))

            result = query.evaluate(repository)


            # Add constraints with 'and_'

            constrained_query = oso.build_query(("allow", actor, "read",
            repository)) \
                .and_(("has_relation", repository, "folder", Value("Folder", "docs")))

            # Different evaluation modes

            exists = query.evaluate()                              # Boolean

            actions = query.evaluate("action")                      # Single
            variable

            pairs = query.evaluate(("action", "repository"))        # Tuple
            variables
        - lang: go
          label: Go
          source: >
            package main


            import (
                "log"
                "os"
                oso "github.com/osohq/go-oso-cloud/v2"
            )


            func main() {
                apiKey := os.Getenv("OSO_CLOUD_API_KEY")
                osoClient := oso.NewClient("https://cloud.osohq.com", apiKey)

            // Basic query building

            actor := oso.NewValue("User", "alice")

            repository := oso.NewValue("Repository", "anvils")

            query := osoClient.BuildQuery(oso.NewQueryFact("allow", actor,
            oso.String("read"), repository))

            repos, err := query.EvaluateValues(repository)


            // Add constraints with 'And'

            folder := oso.NewValue("Folder", "docs")

            constrainedQuery := osoClient.BuildQuery(oso.NewQueryFact("allow",
            actor, oso.String("read"), repository)).
                And(oso.NewQueryFact("has_relation", repository, oso.String("folder"), folder))

            // Different evaluation modes

            allowed, err :=
            query.EvaluateExists()                                    // Boolean

            actions, err :=
            query.EvaluateValues(oso.NewVariable("action"))           // Values
            for variable

            }
        - lang: java
          label: Java
          source: |
            package com.mycompany;

            import java.io.IOException;
            import com.osohq.oso_cloud.Oso;
            import com.osohq.oso_cloud.api.ApiException;
            import com.osohq.oso_cloud.api.Value;

            public class App {
                public static void main(String[] args) {
                    String apiKey = System.getenv("OSO_CLOUD_API_KEY");
                    Oso oso = new Oso(apiKey);
                    
                    try {
                        // Basic query building
                        Value actor = new Value("User", "alice");
                        Value repository = new Value("Repository", "anvils");
                        var query = oso.buildQuery("allow", actor, "read", repository);
                        var result = query.evaluate(repository);
                        
                        // Add constraints with 'and'
                        Value folder = new Value("Folder", "docs");
                        var constrainedQuery = oso.buildQuery("allow", actor, "read", repository)
                            .and("has_relation", repository, "folder", folder);
                        
                        // Different evaluation modes
                        boolean exists = query.evaluate();                      // Boolean
                        var actions = query.evaluate("action");                 // Single variable
                        var pairs = query.evaluate("action", "repository");     // Tuple variables
                    } catch (IOException | ApiException e) {
                        System.err.println("Error: " + e.getMessage());
                    }
                }
            }
        - lang: ruby
          label: Ruby
          source: >
            require 'oso-cloud'


            api_key = ENV.fetch('OSO_CLOUD_API_KEY', nil)

            oso = OsoCloud::Oso.new(url: "https://cloud.osohq.com", api_key:
            api_key)


            # Basic query building

            actor = OsoCloud::Value.new(type: "User", id: "alice")

            repository = OsoCloud::Value.new(type: "Repository", id: "anvils")

            query = oso.build_query(["allow", actor, "read", repository])

            result = query.evaluate(repository)


            # Add constraints with 'and_'

            folder = OsoCloud::Value.new(type: "Folder", id: "docs")

            constrained_query = oso.build_query(["allow", actor, "read",
            repository])
              .and_(["has_relation", repository, "folder", folder])

            # Different evaluation modes

            exists = query.evaluate()                           # Boolean

            actions = query.evaluate("action")                  # Single
            variable

            pairs = query.evaluate(["action", "repository"])    # Tuple
            variables
        - lang: csharp
          label: C#
          source: >
            using OsoCloud;


            string? apiKey =
            Environment.GetEnvironmentVariable("OSO_CLOUD_API_KEY");

            var oso = new Oso("https://api.osohq.com", apiKey);


            // Basic query building

            var actor = new Value("User", "alice");

            var repository = new Value("Repository", "anvils");

            var query = oso.BuildQuery("allow", actor, "read", repository);

            var result = await query.Evaluate(repository);


            // Add constraints with 'And'

            var folder = new Value("Folder", "docs");

            var constrainedQuery = oso.BuildQuery("allow", actor, "read",
            repository)
                .And("has_relation", repository, "folder", folder);

            // Different evaluation modes

            bool exists = await query.Evaluate();                          //
            Boolean

            var actions = await query.Evaluate("action");                  //
            Single variable

            var pairs = await query.Evaluate(new[] { "action", "repository" });
            // Tuple variables
components:
  schemas:
    Query:
      description: A generic query comprising 1+ predicates conjuncted together.
      type: object
      required:
        - calls
        - constraints
        - context_facts
        - predicate
      properties:
        predicate:
          description: >-
            Predicate name and variable names.


            INVARIANT: all variable names must exist in `constraints`. This
            ensures that all variables at least have a type.
          type: array
          items:
            - type: string
            - type: array
              items:
                type: string
          maxItems: 2
          minItems: 2
        calls:
          description: >-
            Predicate name and variable names.


            INVARIANT: all variable names must exist in `constraints`. This
            ensures that all variables at least have a type.
          type: array
          items:
            type: array
            items:
              - type: string
              - type: array
                items:
                  type: string
            maxItems: 2
            minItems: 2
        constraints:
          description: >-
            Map of variable names to their type and value(s). Every variable is
            at least typed and may also be constrained to a set of values.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Constraint'
        context_facts:
          type: array
          items:
            $ref: '#/components/schemas/ConcreteFact'
    QueryResult:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
              nullable: true
    ApiError:
      type: object
      required:
        - message
      properties:
        message:
          type: string
    Constraint:
      description: >-
        Constraints on a variable. All variables must have a type, and they may
        also be constrained to a set of values.
      type: object
      required:
        - type
      properties:
        type:
          description: The type of the variable.
          type: string
        ids:
          description: >-
            The possible values of the variable. `None` means the variable can
            be any value. `Some(["foo"])` means the variable must be exactly
            `"foo"`. `Some(["foo", "bar"])` means the variable can be either
            `"foo"` or `"bar"`. The latter is how we represent `In` expressions
            in the new Query API.
          type: array
          items:
            type: string
          nullable: true
    ConcreteFact:
      description: >-
        A specific piece of authorization-relevant data, ie: a fact.


        `ConcreteFact`s are suitable for storing in the database, since they
        represent the information in a specific, fully-qualified fact. To
        represent the set of facts matching a pattern instead, see [`Fact`].
      type: object
      required:
        - args
        - predicate
      properties:
        predicate:
          type: string
        args:
          type: array
          items:
            $ref: '#/components/schemas/TypedId'
    TypedId:
      type: object
      required:
        - id
        - type
      properties:
        type:
          type: string
        id:
          type: string
  securitySchemes:
    ApiKey:
      description: Requires an API key to access.
      type: http
      scheme: bearer
      bearerFormat: Bearer e_0123_123_token0123

````