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

# Create Tool Request

> Guide: [Enroll your team's devices](https://docs.promptguard.co/shadow-ai/fleet-enrollment#why-per-device-credentials)



## OpenAPI

````yaml /api-reference/openapi-developer.json post /api/v1/tool-requests
openapi: 3.1.0
info:
  title: PromptGuard Developer API
  description: >-
    Public API for developers to integrate PromptGuard security into their
    applications
  version: 1.0.0
servers:
  - url: https://api.promptguard.co
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/v1/tool-requests:
    post:
      tags:
        - tool-requests
      summary: Create Tool Request
      description: >-
        Guide: [Enroll your team's
        devices](https://docs.promptguard.co/shadow-ai/fleet-enrollment#why-per-device-credentials)
      operationId: create_tool_request_api_v1_tool_requests_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateToolRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceToolRequest'
              example:
                id: 7e3a9c1d-2f5b-4a8e-b6d0-9c4f1e2a7b35
                code: TR-3F9A
                requested_host: claude.ai
                requested_name: Claude
                justification: Drafting customer emails
                status: pending
                created_at: '2026-10-31T09:20:44.102937+00:00'
                decided_at: null
        '401':
          description: Missing, malformed, unknown, disabled or expired API key
          content:
            application/json:
              examples:
                missing_api_key:
                  summary: No X-API-Key header
                  value:
                    error:
                      message: >-
                        PromptGuard API key required. Please provide via
                        X-API-Key header.
                      type: authentication_error
                      code: missing_api_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#missing_api_key
                malformed_api_key:
                  summary: Not a pg_live_ key
                  value:
                    error:
                      message: Invalid API key format
                      type: authentication_error
                      code: invalid_api_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#invalid_api_key
                unknown_api_key:
                  summary: No such key
                  value:
                    error:
                      message: Invalid API key
                      type: authentication_error
                      code: invalid_api_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#invalid_api_key
                disabled_api_key:
                  summary: Key disabled
                  value:
                    error:
                      message: API key is disabled
                      type: authentication_error
                      code: disabled_api_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#disabled_api_key
                expired_api_key:
                  summary: Key expired
                  value:
                    error:
                      message: API key has expired
                      type: authentication_error
                      code: expired_api_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#expired_api_key
              schema:
                $ref: '#/components/schemas/AuthErrorEnvelope'
        '403':
          description: Refused by the key's scopes or the organization's IP allowlist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                scope_denied:
                  summary: The key's scopes exclude this endpoint
                  value:
                    error:
                      message: >-
                        This endpoint needs the `shadow:write` scope, which this
                        API key does not hold. Create a key that includes it, or
                        use an unrestricted key.
                      type: insufficient_scope
                      code: scope_denied
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#scope_denied
                scan_only_credential:
                  summary: A scan-only device credential
                  value:
                    error:
                      message: This credential is scan-only; endpoint not permitted.
                      type: insufficient_scope
                      code: scope_denied
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#scope_denied
                read_only_key:
                  summary: A SIEM export key
                  value:
                    error:
                      message: >-
                        This is a read-only export key. It may only GET
                        /api/v1/alerts, /api/v1/audit-events,
                        /api/v1/audit-events/stream, /api/v1/interactions and
                        /api/v1/interactions/stream.
                      type: insufficient_scope
                      code: read_only_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#read_only_key
                ip_not_allowed:
                  summary: Caller IP outside the allowlist
                  value:
                    error:
                      message: Request IP is not in the organization's allowlist
                      type: permission_error
                      code: ip_not_allowed
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#ip_not_allowed
                ip_allowlist_error:
                  summary: Allowlist could not be checked
                  value:
                    error:
                      message: IP allowlist validation failed
                      type: permission_error
                      code: ip_allowlist_error
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#ip_allowlist_error
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorEnvelope'
        '429':
          description: Per-minute rate limit reached; retry after `retry_after` seconds
          content:
            application/json:
              examples:
                rate_limit_exceeded:
                  summary: Per-minute limit reached
                  value:
                    error:
                      message: >-
                        Rate limit exceeded: your plan allows 60 requests per
                        minute. Please retry later.
                      type: rate_limit_exceeded
                      code: rate_limit_exceeded
                      retry_after: 42
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#rate_limit_exceeded
              schema:
                $ref: '#/components/schemas/RateLimitErrorEnvelope'
      externalDocs:
        description: 'Guide: Enroll your team''s devices'
        url: >-
          https://docs.promptguard.co/shadow-ai/fleet-enrollment#why-per-device-credentials
components:
  schemas:
    CreateToolRequest:
      properties:
        requested_host:
          type: string
          maxLength: 255
          title: Requested Host
        requested_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Requested Name
        justification:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Justification
      type: object
      required:
        - requested_host
      title: CreateToolRequest
    DeviceToolRequest:
      properties:
        id:
          type: string
          title: Id
        code:
          type: string
          title: Code
        requested_host:
          type: string
          title: Requested Host
        requested_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Requested Name
        justification:
          anyOf:
            - type: string
            - type: 'null'
          title: Justification
        status:
          type: string
          title: Status
          description: pending | approved | denied | cancelled
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
        decided_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Decided At
      type: object
      required:
        - id
        - code
        - requested_host
        - requested_name
        - justification
        - status
        - created_at
        - decided_at
      title: DeviceToolRequest
      description: >-
        One "request a tool" row as the filing device sees it. Timestamps are
        ISO 8601.
    AuthErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
          examples:
            - code: missing_api_key
              message: >-
                PromptGuard API key required. Please provide via X-API-Key
                header.
              type: authentication_error
      type: object
      required:
        - error
      title: AuthErrorEnvelope
    ErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
        - error
      title: ErrorEnvelope
    ValidationErrorEnvelope:
      description: The developer API's 422 (`shared/infrastructure/framework_errors.py`).
      properties:
        error:
          $ref: '#/components/schemas/ValidationErrorDetail'
        detail:
          deprecated: true
          description: >-
            The same list as `error.details`, in FastAPI's old shape. Removed on
            2027-02-11; read `error.details`
          items:
            $ref: '#/components/schemas/ValidationErrorField'
          title: Detail
          type: array
      required:
        - error
        - detail
      title: ValidationErrorEnvelope
      type: object
      example:
        error:
          message: 'The request is invalid: body.messages: Field required'
          type: invalid_request_error
          code: invalid_request
          details:
            - type: missing
              loc:
                - body
                - messages
              msg: Field required
              input:
                direction: input
          error_id: 3f0b8c1e-6a0e-4d52-9a57-0c2a9a7f5b11
          doc_url: >-
            https://docs.promptguard.co/production/error-handling#invalid_request
        detail:
          - type: missing
            loc:
              - body
              - messages
            msg: Field required
            input:
              direction: input
    RateLimitErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/RateLimitErrorDetail'
      type: object
      required:
        - error
      title: RateLimitErrorEnvelope
    ErrorDetail:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable error description
        type:
          type: string
          title: Type
          description: Error category, e.g. 'authentication_error'
        code:
          type: string
          title: Code
          description: Machine-readable error code
        doc_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Url
          description: >-
            The error catalogue's entry for `code` (cause and fix); present when
            the catalogue documents the code
      type: object
      required:
        - message
        - type
        - code
      title: ErrorDetail
    ValidationErrorDetail:
      properties:
        message:
          description: The failed fields, one line
          title: Message
          type: string
        type:
          description: '''invalid_request_error'''
          title: Type
          type: string
        code:
          description: '''invalid_request'''
          title: Code
          type: string
        details:
          description: Each field that failed
          items:
            $ref: '#/components/schemas/ValidationErrorField'
          title: Details
          type: array
        error_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Equals the X-Request-ID header
          title: Error Id
        doc_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            The error catalogue's entry for `code` (cause and fix); present when
            the catalogue documents the code
          title: Doc Url
      required:
        - message
        - type
        - code
        - details
      title: ValidationErrorDetail
      type: object
    ValidationErrorField:
      description: One field that failed validation, as FastAPI reports it.
      properties:
        loc:
          description: The field's path, e.g. ['body', 'messages']
          items:
            anyOf:
              - type: string
              - type: integer
          title: Loc
          type: array
        msg:
          description: What is wrong with it
          title: Msg
          type: string
        type:
          description: The kind of failure, e.g. 'missing'
          title: Type
          type: string
        input:
          default: null
          description: The value that was sent
          title: Input
        ctx:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          description: The limit it broke, where there is one
          title: Ctx
      required:
        - loc
        - msg
        - type
      title: ValidationErrorField
      type: object
    RateLimitErrorDetail:
      properties:
        message:
          type: string
          title: Message
        type:
          type: string
          title: Type
          description: '''rate_limit_exceeded'''
        code:
          type: string
          title: Code
          description: '''rate_limit_exceeded'''
        retry_after:
          type: integer
          title: Retry After
          description: Seconds until the window resets; also `Retry-After`
        doc_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Url
          description: >-
            The error catalogue's entry for `code` (cause and fix); present when
            the catalogue documents the code
      type: object
      required:
        - message
        - type
        - code
        - retry_after
      title: RateLimitErrorDetail
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        PromptGuard API key for developer endpoints. Keys start with pg_live_
        and are created in the dashboard.

````

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