> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnara.com/llms.txt > Use this file to discover all available pages before exploring further. # Create project model grant > Lets a project's agent configs use a configured model and returns the new grant. Optional overrides can narrow the model for that project (lower token limits, tools or reasoning turned off, fewer reasoning efforts or modalities) and set its per-request defaults within those limits. ## OpenAPI ````yaml /api-reference/openapi.yaml post /orgs/{orgID}/projects/{projectID}/model-grants openapi: 3.1.2 info: title: Omnara API version: 0.1.0 description: Public HTTP API contract for Omnara. servers: - url: https://api.omnara.com/v1 description: Hosted Omnara - url: /api/v1 description: Self-hosted Omnara, relative to the deployment origin security: - bearerAuth: [] - browserSessionCookie: [] tags: - name: Agents description: >- Launch agents, send inputs, manage the input backlog, and work with tool calls. externalDocs: description: Guide url: https://docs.omnara.com/agents/overview - name: Interactions description: List and resolve the approvals and questions that pause an agent. externalDocs: description: Guide url: https://docs.omnara.com/events/interactions - name: Actors description: Attribute agent inputs and interaction responses to external users. externalDocs: description: Guide url: >- https://docs.omnara.com/events/sending-input#who-said-that-actors-and-attribution - name: Events description: Read or stream the agent timeline, list turns, and download artifacts. externalDocs: description: Guide url: https://docs.omnara.com/events/streaming - name: Configs and Profiles description: >- Create agent configs, manage reusable launch profiles, and set up integrations. externalDocs: description: Guide url: https://docs.omnara.com/agents/configuration - name: Integrations description: >- Connect project integrations, route conversations, and manage launch settings. externalDocs: description: Guide url: https://docs.omnara.com/integrations/overview - name: Models description: Configure model providers and models, and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/organization/model-providers - name: Machines description: Register machines, control project access, and manage daemon tokens. externalDocs: description: Guide url: https://docs.omnara.com/machines/connect - name: Machine Pools description: Define machine pools and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/machines/pools - name: Secrets description: >- Manage secret ownership and versions, and inspect or grant project availability. externalDocs: description: Guide url: https://docs.omnara.com/organization/secrets - name: Skills description: Manage versioned skill ownership and load skill instructions on demand. externalDocs: description: Guide url: https://docs.omnara.com/tools/skills - name: Organizations and Projects description: Create organizations and projects and manage membership. externalDocs: description: Guide url: https://docs.omnara.com/organization/members - name: Users and API Keys description: >- The authenticated user, personal and organization API keys, and invitations. externalDocs: description: Guide url: https://docs.omnara.com/api/authentication - name: Machine Daemon description: Routes the Omnara machine daemon uses to connect a machine. paths: /orgs/{orgID}/projects/{projectID}/model-grants: parameters: - name: orgID in: path description: Organization ID (org_...). required: true schema: type: string pattern: ^org_[a-z2-7]{26}$ - name: projectID in: path description: Project ID (proj_...). required: true schema: type: string pattern: ^proj_[a-z2-7]{26}$ post: tags: - Models summary: Create project model grant description: >- Lets a project's agent configs use a configured model and returns the new grant. Optional overrides can narrow the model for that project (lower token limits, tools or reasoning turned off, fewer reasoning efforts or modalities) and set its per-request defaults within those limits. operationId: createProjectModelGrant requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateProjectModelGrantRequest' responses: '201': description: Created route response. content: application/json: schema: $ref: '#/components/schemas/ProjectModelGrantEnvelope' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '503': $ref: '#/components/responses/ServiceUnavailable' 4XX: $ref: '#/components/responses/ClientError' 5XX: $ref: '#/components/responses/ServerError' security: - bearerAuth: [] - browserSessionCookie: [] csrfHeader: [] components: schemas: CreateProjectModelGrantRequest: type: object description: >- Grant a project access to a configured model. Optional fields can narrow the model's limits for this project; omitted fields inherit from the org-level configured model. additionalProperties: false required: - configured_model_id properties: configured_model_id: $ref: '#/components/schemas/ConfiguredModelID' context_window_tokens: type: integer minimum: 2 maximum: 2147483647 description: >- Optional project context budget for input and output tokens. Cannot exceed the configured model's budget. Triggers compaction when estimated input exceeds the remaining budget after output and safety reserves. The turn fails if compaction cannot make it fit. max_output_tokens: type: integer minimum: 1 maximum: 2147483647 description: >- Optional project output-token ceiling. Cannot exceed the configured model's ceiling. default_max_output_tokens: type: integer minimum: 1 maximum: 2147483647 description: Optional project default per-request output-token cap. default_cache_retention: $ref: '#/components/schemas/ModelCacheRetention' supports_tools: type: boolean description: >- Optional project-level tool-use gate. Can disable tools, but cannot enable tools when the configured model does not support them. supports_reasoning: type: boolean description: >- Optional project-level reasoning gate. Can disable reasoning, but cannot enable reasoning when the configured model does not support it. default_reasoning_effort: type: string description: Optional project default reasoning effort. supported_reasoning_efforts: type: array description: >- Optional project subset of configured-model reasoning efforts. If this excludes the inherited default_reasoning_effort, set default_reasoning_effort on the grant too. items: type: string input_modalities: type: array description: >- Optional project subset of configured-model input types (text, image, or file). Empty or omitted means inherit. items: type: string output_modalities: type: array description: >- Optional project subset of configured-model output types. Empty or omitted means inherit. items: type: string ProjectModelGrantEnvelope: type: object additionalProperties: false required: - grant properties: grant: $ref: '#/components/schemas/ProjectModelGrant' ConfiguredModelID: type: string pattern: ^mdl_[a-z2-7]{26}$ ModelCacheRetention: type: string description: >- Prompt-cache preference for model requests; `short` when omitted. `short` applies the route's default caching (explicit cache breakpoints where the provider requires them) and, where the route accepts one, a stable conversation key for cache-aware routing. `long` prefers the route's extended cache lifetime where one exists (currently Anthropic's one-hour cache, which on Bedrock requires Claude 4.5 or newer) and behaves like `short` elsewhere. `none` sends no Omnara-managed cache controls or conversation key; providers may still cache prefixes on their own. enum: - none - short - long ProjectModelGrant: type: object additionalProperties: false required: - id - org_id - project_id - configured_model_id - supported_reasoning_efforts - input_modalities - output_modalities - created_at - updated_at properties: id: $ref: '#/components/schemas/ProjectModelGrantID' org_id: $ref: '#/components/schemas/OrganizationID' project_id: $ref: '#/components/schemas/ProjectID' configured_model_id: $ref: '#/components/schemas/ConfiguredModelID' context_window_tokens: type: - integer - 'null' description: >- Project context budget for input and output tokens, or omitted/null to inherit from the configured model. Triggers compaction when estimated input exceeds the remaining budget after output and safety reserves. The turn fails if compaction cannot make it fit. max_output_tokens: type: - integer - 'null' description: >- Project output-token ceiling, or omitted/null to inherit from the configured model. default_max_output_tokens: type: - integer - 'null' description: >- Project default per-request output-token cap, or omitted/null to inherit from the configured model. default_cache_retention: $ref: '#/components/schemas/ModelCacheRetention' supports_tools: type: - boolean - 'null' description: >- Project-level tool-use override, or omitted/null to inherit from the configured model. supports_reasoning: type: - boolean - 'null' description: >- Project-level reasoning override, or omitted/null to inherit from the configured model. default_reasoning_effort: type: string description: >- Project default reasoning effort, or omitted/empty to inherit from the configured model. supported_reasoning_efforts: type: array description: >- Project subset of configured-model reasoning efforts. Empty means inherit. When non-empty, default_reasoning_effort must resolve to one of these values. items: type: string input_modalities: type: array description: >- Project subset of configured-model input types (text, image, or file). Empty means inherit. items: type: string output_modalities: type: array description: >- Project subset of configured-model output types. Empty means inherit. items: type: string created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' Error: type: object additionalProperties: false required: - error - code properties: error: type: string description: Human-readable error message. Do not match on it programmatically. current_digest: type: string pattern: ^sha256:[0-9a-f]{64}$ description: >- Current file digest for file_content_conflict or expected_digest_required; absent if the file no longer exists. A replacement must be confirmed before retrying with this digest. issues: type: array description: >- Field-level problems when a submitted document (such as an agent config source) failed validation. Absent for errors that are not about a specific field. items: $ref: '#/components/schemas/AgentConfigErrorIssue' code: type: string description: Stable error code for programmatic handling. x-go-type: ErrorCode x-extensible-enum: - invalid_request - unauthorized - forbidden - not_found - conflict - file_content_conflict - file_read_only - expected_digest_required - not_a_file - gone - request_too_large - unsupported_media_type - unprocessable - upstream_unavailable - rate_limited - internal_error - service_unavailable - idempotency_key_conflict - agent_backlog_full - state_transition_conflict - managed_work_admission_denied - pending_work - not_wake_capable - daemon_runtime_unregistered - validation_failed - csrf_check_failed - authentication_unavailable ClientErrorCode: type: string description: >- Stable error code carried by 4XX statuses. Subset of the Error code enum whose statuses are client errors. x-extensible-enum: - invalid_request - validation_failed - unauthorized - forbidden - csrf_check_failed - not_found - conflict - file_content_conflict - file_read_only - expected_digest_required - not_a_file - idempotency_key_conflict - agent_backlog_full - state_transition_conflict - pending_work - not_wake_capable - gone - daemon_runtime_unregistered - request_too_large - unsupported_media_type - unprocessable - upstream_unavailable - rate_limited ServerErrorCode: type: string description: >- Stable error code carried by 5XX statuses. Subset of the Error code enum whose statuses are server errors. x-extensible-enum: - internal_error - service_unavailable - authentication_unavailable ProjectModelGrantID: type: string pattern: ^pmog_[a-z2-7]{26}$ OrganizationID: type: string pattern: ^org_[a-z2-7]{26}$ ProjectID: description: Project ID (proj_...). type: string pattern: ^proj_[a-z2-7]{26}$ Timestamp: type: string format: date-time AgentConfigErrorIssue: type: object additionalProperties: false required: - path - message properties: path: type: string description: >- JSON Pointer (RFC 6901) to the offending field in the submitted document. An empty string refers to the whole document. message: type: string description: Human-readable description of the problem with this field. line: type: integer minimum: 1 description: >- 1-based line of the offending field in the submitted source, when it can be located. column: type: integer minimum: 1 description: >- 1-based column of the offending field in the submitted source, when it can be located. responses: BadRequest: description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication is required or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The authenticated principal is not authorized. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found or is not visible. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- The request conflicts with current resource state or idempotency history. content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: The service dependency required to satisfy the request is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' ClientError: description: >- Any other client error. The body carries the shared Error envelope restricted to client error codes; statuses with a dedicated response above are documented precisely. content: application/json: schema: type: object additionalProperties: false required: - error - code properties: error: type: string description: >- Human-readable error message. Do not match on it programmatically. code: $ref: '#/components/schemas/ClientErrorCode' ServerError: description: >- Any other server error. The body carries the shared Error envelope restricted to server error codes. content: application/json: schema: type: object additionalProperties: false required: - error - code properties: error: type: string description: >- Human-readable error message. Do not match on it programmatically. code: $ref: '#/components/schemas/ServerErrorCode' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Omnara personal or organization access token description: An opaque Omnara personal or organization bearer token. browserSessionCookie: type: apiKey in: cookie name: __Host-omnara_session description: >- Browser session cookie. HTTPS deployments use __Host-omnara_session; local HTTP development uses omnara_session. csrfHeader: type: apiKey in: header name: X-Omnara-Csrf description: >- CSRF token header required for browser-session mutations. The value must match the session's CSRF cookie. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.