Atrahasis Extensions
Custom OpenAPI Extensions
Atrahasis uses vendor extensions (x-atrahasis-*) to store application-specific data in your OpenAPI spec. These extensions enable features like test assertions, auth configurations, and project metadata.
Key Concepts
- • OpenAPI Compliant - All x-* extensions are valid per spec
- • Round-Trip Safe - Extensions survive import/export cycles
- • Sync Aware - Preserved during bi-directional sync
Available Extensions
Atrahasis defines the following vendor extensions:
| Extension | Location | Purpose |
|---|---|---|
| x-atrahasis-assertions | Operation | Test assertions for responses |
| x-atrahasis-auth | Operation | Per-endpoint auth configuration |
| x-atrahasis-enabled | Parameter | Enable/disable individual parameters |
| x-atrahasis-env-id | Server | Stable environment identifier |
| x-atrahasis-env-name | Server | Custom environment display name |
| x-atrahasis-project-id | Root | Project tracking ID |
| x-atrahasis-version | Root | Atrahasis format version |
| x-atrahasis-module-id | Tag | Module/folder identifier |
| x-atrahasis-endpoint-id | Operation | Endpoint tracking ID |
x-atrahasis-assertions
TestingDefine test assertions that run automatically when you send a request. Assertions verify response status, headers, body content, and more.
Full Example
Assertion Types
- status - HTTP status code
- response_time - Response time in ms
- header - Header value check
- json_path - JSON path validation
- body - Raw body content
Comparison Operators
- equals / not_equals
- contains / not_contains
- exists / not_exists
- greater_than / less_than
- is_empty / is_not_empty
- matches_regex / is_type
x-atrahasis-auth
AuthOverride the authentication method for specific operations. Useful when an endpoint needs different auth than the global security setting.
Bearer Token Override
API Key Override
Basic Auth Override
No Auth (Public)
Security Note
Auth credentials in x-atrahasis-auth are stored in your spec file. Use environment variables or exclude this extension when sharing specs externally.
x-atrahasis-enabled
ParameterEnable or disable individual parameters. Useful for temporarily turning off specific query params or headers without removing them from the spec.
enabled: true (default)
Parameter is included when sending requests.
enabled: false
Parameter is skipped when sending requests. Still visible in UI.
Environment Extensions
ServerControl how servers map to Atrahasis environments with stable IDs and custom display names.
x-atrahasis-env-id & x-atrahasis-env-name
x-atrahasis-env-id
Stable identifier for the environment. Preserves selection across re-imports even if URL or description changes.
x-atrahasis-env-name
Display name in the UI. Takes precedence over the server'sdescription field.
Project Metadata
TrackingInternal tracking extensions added by Atrahasis for project management. Generally you don't need to edit these manually.
Auto-Generated IDs
Project, module, and endpoint IDs are generated automatically by Atrahasis. They enable stable sync between spec and project even when names change.
Round-Trip Fidelity
Atrahasis preserves your extensions through the import → edit → export cycle:
Extensions you didn't touch remain exactly as imported. Atrahasis only modifies sections you actually edit.
Preservation Guarantee
Unknown vendor extensions (x-*) from other tools are also preserved. Atrahasis only manages its own x-atrahasis-* namespace.