ORQIS
Documentation

Orqis Docs

Guides on how to create effective AI agents from your API specifications.

How to Write Better OpenAPI Specs

To ensure the AI can accurately understand and interact with your API, follow these best practices when writing your OpenAPI specification:

  • Use Clear Descriptions: Provide detailed descriptions for paths, operations, parameters, and schemas. Explain the purpose and expected values.
  • Define Examples: Include examples for request bodies and responses. This helps the AI understand the expected data format.
  • Specify Operation IDs: Assign unique and descriptive operationId values to each operation.
  • Accurate Schemas: Ensure your request and response schemas accurately reflect the data structure, including data types and constraints (e.g., required fields, enums).
  • Handle Authentication: Clearly define security schemes (e.g., API Keys, OAuth2) in the securitySchemes and apply them using the security field.

How the AI Interprets Endpoints

The AI agent analyzes your OpenAPI spec to understand:

  • Available API operations (endpoints and methods).
  • Required and optional parameters for each operation.
  • Expected request body structures.
  • Possible response structures and status codes.
  • Authentication requirements.

Based on a user's natural language query, the AI identifies the most relevant API operation(s), extracts necessary parameters from the query, constructs the API request, and interprets the response to provide an answer.

Security, Rate Limiting & Error Handling

Security: The agent relies on the security schemes defined in your OpenAPI spec. Ensure your API server properly enforces these schemes. The agent itself does not add an extra layer of security beyond calling your API as specified.
Rate Limiting: API calls made by the agent count towards your API's rate limits just like any other client. Ensure your API has appropriate rate limiting in place. The agent does not currently implement its own rate limiting.
Error Handling: The agent attempts to interpret API error responses based on your spec, but clear error definitions in the spec lead to better results.