openapi: 3.1.0
info:
  title: Anthropic Prompt Tools API
  description: |
    Manage prompts with generation, improvement, and templatization capabilities.

    The prompt tools APIs are in a closed research preview. These APIs are a set
    of tools to generate and improve prompts, similar to what's available in the
    Anthropic Workbench, and are intended for use by other prompt engineering
    platforms and playgrounds.
  version: 1.0.0
  contact:
    name: Anthropic Support
    url: https://support.anthropic.com
  license:
    name: Anthropic Terms of Service
    url: https://www.anthropic.com/terms

servers:
  - url: https://api.anthropic.com
    description: Production Server

security:
  - ApiKeyAuth: []

tags:
  - name: Prompt Generation
    description: APIs for generating well-written prompts for specified tasks
  - name: Prompt Improvement
    description: APIs for enhancing existing prompts with feedback
  - name: Prompt Templatization
    description: APIs for converting prompts into reusable templates with variables

paths:
  /v1/experimental/generate_prompt:
    post:
      summary: Anthropic Generate A Prompt
      description: |
        Generate a well-written prompt for a specified task. This API creates
        prompts that can be used directly with the Messages API.

        **Requirements:**
        - Must have joined the closed research preview for prompt tools APIs
        - Must use the API directly (not available in SDK)
        - Must include the beta header `prompt-tools-2025-04-02`
      operationId: generatePrompt
      tags:
        - Prompt Generation
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: ""
        delay: 100
      parameters:
        - $ref: '#/components/parameters/AnthropicBetaHeader'
        - $ref: '#/components/parameters/ApiKeyHeader'
        - $ref: '#/components/parameters/ContentTypeHeader'
        - $ref: '#/components/parameters/BrowserAccessHeader'
        - $ref: '#/components/parameters/AnthropicVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratePromptRequest'
            examples:
              ChefExample:
                $ref: '#/components/examples/GeneratePromptRequestChefExample'
              DefaultExample:
                $ref: '#/components/examples/GeneratePromptRequestDefaultExample'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratePromptResponse'
              examples:
                ChefResponse:
                  $ref: '#/components/examples/GeneratePromptResponseChefExample'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestExample:
                  $ref: '#/components/examples/ErrorBadRequestExample'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedExample:
                  $ref: '#/components/examples/ErrorUnauthorizedExample'
        '403':
          description: Forbidden - Access denied or not in closed research preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ForbiddenExample:
                  $ref: '#/components/examples/ErrorForbiddenExample'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                RateLimitExample:
                  $ref: '#/components/examples/ErrorRateLimitExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ServerErrorExample:
                  $ref: '#/components/examples/ErrorServerExample'

  /v1/experimental/improve_prompt:
    post:
      summary: Anthropic Improve A Prompt
      description: |
        Create a new-and-improved prompt guided by feedback. This API takes an
        existing prompt and enhances it based on provided feedback or general
        prompt engineering best practices.

        **Requirements:**
        - Must have joined the closed research preview for prompt tools APIs
        - Must use the API directly (not available in SDK)
        - Must include the beta header `prompt-tools-2025-04-02`
        - Messages must contain only text-only content blocks
        - No tool calls, images, or prompt caching blocks allowed
        - Only contiguous user messages with text content are permitted
      operationId: improvePrompt
      tags:
        - Prompt Improvement
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: ""
        delay: 100
      parameters:
        - $ref: '#/components/parameters/AnthropicBetaHeader'
        - $ref: '#/components/parameters/ApiKeyHeader'
        - $ref: '#/components/parameters/ContentTypeHeader'
        - $ref: '#/components/parameters/BrowserAccessHeader'
        - $ref: '#/components/parameters/AnthropicVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImprovePromptRequest'
            examples:
              DefaultExample:
                $ref: '#/components/examples/ImprovePromptRequestDefaultExample'
              RecipeWithExampleExample:
                $ref: '#/components/examples/ImprovePromptRequestRecipeExample'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImprovePromptResponse'
              examples:
                ImprovedRecipeResponse:
                  $ref: '#/components/examples/ImprovePromptResponseExample'
        '400':
          description: Bad Request - Invalid input parameters or unsupported content types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestExample:
                  $ref: '#/components/examples/ErrorBadRequestExample'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedExample:
                  $ref: '#/components/examples/ErrorUnauthorizedExample'
        '403':
          description: Forbidden - Access denied or not in closed research preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ForbiddenExample:
                  $ref: '#/components/examples/ErrorForbiddenExample'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                RateLimitExample:
                  $ref: '#/components/examples/ErrorRateLimitExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ServerErrorExample:
                  $ref: '#/components/examples/ErrorServerExample'

  /v1/experimental/templatize_prompt:
    post:
      summary: Anthropic Templatize A Prompt
      description: |
        Templatize a prompt by identifying and extracting variables. This API
        analyzes a prompt and converts specific values into reusable template
        variables with placeholders.

        **Requirements:**
        - Must have joined the closed research preview for prompt tools APIs
        - Must use the API directly (not available in SDK)
        - Must include the beta header `prompt-tools-2025-04-02`
        - Messages must contain only text-only content blocks
        - No tool calls, images, or prompt caching blocks allowed
        - Only contiguous user messages with text content are permitted
      operationId: templatizePrompt
      tags:
        - Prompt Templatization
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: ""
        delay: 100
      parameters:
        - $ref: '#/components/parameters/AnthropicBetaHeader'
        - $ref: '#/components/parameters/ApiKeyHeader'
        - $ref: '#/components/parameters/ContentTypeHeader'
        - $ref: '#/components/parameters/BrowserAccessHeader'
        - $ref: '#/components/parameters/AnthropicVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplatizePromptRequest'
            examples:
              DefaultExample:
                $ref: '#/components/examples/TemplatizePromptRequestDefaultExample'
              TranslationWithSystemExample:
                $ref: '#/components/examples/TemplatizePromptRequestTranslationExample'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatizePromptResponse'
              examples:
                TemplatizedTranslationResponse:
                  $ref: '#/components/examples/TemplatizePromptResponseExample'
        '400':
          description: Bad Request - Invalid input parameters or unsupported content types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestExample:
                  $ref: '#/components/examples/ErrorBadRequestExample'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedExample:
                  $ref: '#/components/examples/ErrorUnauthorizedExample'
        '403':
          description: Forbidden - Access denied or not in closed research preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ForbiddenExample:
                  $ref: '#/components/examples/ErrorForbiddenExample'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                RateLimitExample:
                  $ref: '#/components/examples/ErrorRateLimitExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ServerErrorExample:
                  $ref: '#/components/examples/ErrorServerExample'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication

  parameters:
    AnthropicBetaHeader:
      name: anthropic-beta
      in: header
      description: |
        Optional header to specify the beta version(s) you want to use.
        To use multiple betas, use a comma separated list like `beta1,beta2`
        or specify the header multiple times for each beta.
      required: false
      schema:
        type: array
        items:
          type: string
        example:
          - prompt-tools-2025-04-02
      style: simple
      explode: false

    ApiKeyHeader:
      name: x-api-key
      in: header
      required: true
      description: A valid API token.
      schema:
        type: string

    ContentTypeHeader:
      name: Content-Type
      in: header
      required: true
      description: The content type.
      schema:
        type: string
        default: application/json

    BrowserAccessHeader:
      name: anthropic-dangerous-direct-browser-access
      in: header
      required: false
      description: Enable CORS.
      schema:
        type: string
        default: "true"

    AnthropicVersionHeader:
      name: anthropic-version
      in: header
      required: true
      description: Which version of the Anthropic API to use.
      schema:
        type: string
        default: '2023-06-01'

  schemas:
    # Common Schemas
    TextContentBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
          description: The type of content block
        text:
          type: string
          description: The text content

    PromptMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
          description: The role of the message sender
        content:
          type: array
          description: The content of the message
          items:
            $ref: '#/components/schemas/TextContentBlock'

    UsageInfo:
      type: object
      description: Usage information
      required:
        - input_tokens
        - output_tokens
      properties:
        input_tokens:
          type: integer
          description: Number of input tokens used
          minimum: 0
        output_tokens:
          type: integer
          description: Number of output tokens generated
          minimum: 0

    ErrorResponse:
      type: object
      required:
        - type
        - message
      properties:
        type:
          type: string
          description: The type of error
        message:
          type: string
          description: A human-readable error message

    # Generate Prompt Schemas
    GeneratePromptRequest:
      type: object
      required:
        - task
      properties:
        task:
          type: string
          description: |
            Description of the prompt's purpose.
            The `task` parameter tells Claude what the prompt should do
            or what kind of role or functionality you want to create.
            This helps guide the prompt generation process toward your
            intended use case.
        target_model:
          type: string
          nullable: true
          default:
          description: |
            The model this prompt will be used for. This optional
            parameter helps us understand which models our prompt tools
            are being used with, but it doesn't currently affect
            functionality.
          minLength: 1
          maxLength: 256

    GeneratePromptResponse:
      type: object
      required:
        - messages
        - system
        - usage
      properties:
        messages:
          type: array
          description: |
            The response contains a list of message objects in the
            same format used by the Messages API. Typically includes a
            user message with the complete generated prompt text, and
            may include an assistant message with a prefill to guide
            the model's initial response.
          items:
            $ref: '#/components/schemas/PromptMessage'
        system:
          type: string
          default: ''
          description: |
            Currently, the `system` field is always returned as an
            empty string (""). In future iterations, this field may
            contain generated system prompts.
        usage:
          $ref: '#/components/schemas/UsageInfo'

    # Improve Prompt Schemas
    ImprovePromptRequest:
      type: object
      required:
        - messages
      properties:
        messages:
          type: array
          description: |
            The prompt to improve, structured as a list of message objects.
            Each message must contain only text-only content blocks and
            not include tool calls, images, or prompt caching blocks.
            Only contiguous user messages with text content are allowed.
            Assistant prefill is permitted.
          items:
            $ref: '#/components/schemas/PromptMessage'
        feedback:
          type: string
          nullable: true
          description: |
            Feedback for improving the prompt.
            Use this parameter to share specific guidance on what
            aspects of the prompt should be enhanced or modified.
            When not set, the API will improve the prompt using general
            prompt engineering best practices.
        system:
          type: string
          nullable: true
          description: |
            The existing system prompt to incorporate, if any.
            Note that while system prompts typically appear as separate
            parameters in standard API calls, in the improve_prompt
            response, the system content will be incorporated directly
            into the returned user message.
        target_model:
          type: string
          nullable: true
          default:
          description: |
            The model this prompt will be used for. This optional
            parameter helps us understand which models our prompt tools
            are being used with, but it doesn't currently affect
            functionality.
          minLength: 1
          maxLength: 256

    ImprovePromptResponse:
      type: object
      required:
        - messages
        - system
        - usage
      properties:
        messages:
          type: array
          description: |
            The improved prompt, incorporating the provided feedback
            and prompt engineering best practices.
          items:
            $ref: '#/components/schemas/PromptMessage'
        system:
          type: string
          description: |
            Currently, the system field is always returned as an empty
            string (""). In future iterations, this field may contain
            generated system prompts.
        usage:
          $ref: '#/components/schemas/UsageInfo'

    # Templatize Prompt Schemas
    TemplatizePromptRequest:
      type: object
      required:
        - messages
      properties:
        messages:
          type: array
          description: |
            The prompt to templatize, structured as a list of message objects.
            Each message must contain only text-only content blocks and
            not include tool calls, images, or prompt caching blocks.
            Only contiguous user messages with text content are allowed.
            Assistant prefill is permitted.
          items:
            $ref: '#/components/schemas/PromptMessage'
        system:
          type: string
          nullable: true
          description: |
            The existing system prompt to templatize.
            Note that this differs from the Messages API; it is strictly
            a string.
            If provided, variables will be identified and replaced in
            the system prompt as well.

    TemplatizePromptResponse:
      type: object
      required:
        - messages
        - system
        - usage
        - variable_values
      properties:
        messages:
          type: array
          description: |
            The templatized prompt with variable placeholders.
            The response includes the input messages with specific
            values replaced by variable placeholders. These messages
            maintain the original message structure but contain
            uppercase variable names in place of concrete values.
          items:
            $ref: '#/components/schemas/PromptMessage'
        system:
          type: string
          description: |
            The input system prompt with variables identified and replaced.
            If no system prompt was provided in the original request,
            this field will be an empty string.
        usage:
          $ref: '#/components/schemas/UsageInfo'
        variable_values:
          type: object
          description: |
            A mapping of template variable names to their original
            values, as extracted from the input prompt during
            templatization. Each key represents a variable name
            identified in the templatized prompt, and each value
            contains the corresponding content from the original
            prompt that was replaced by that variable.
          additionalProperties:
            type: string

  examples:
    # Generate Prompt Request Examples
    GeneratePromptRequestChefExample:
      summary: Chef for meal prep service
      value:
        task: a chef for a meal prep planning service
        target_model: claude-3-7-sonnet-20250219

    GeneratePromptRequestDefaultExample:
      summary: Basic task only
      value:
        task: a helpful writing assistant for creative fiction

    # Generate Prompt Response Examples
    GeneratePromptResponseChefExample:
      summary: Chef prompt response
      value:
        messages:
          - role: user
            content:
              - type: text
                text: "You are a chef for a meal prep planning service. Your role is to help users plan their weekly meals, create shopping lists, and provide cooking instructions. Always consider dietary restrictions and preferences when making suggestions."
          - role: assistant
            content:
              - type: text
                text: "<recipe_planning>"
        system: ""
        usage:
          input_tokens: 25
          output_tokens: 150

    # Improve Prompt Request Examples
    ImprovePromptRequestDefaultExample:
      summary: Simple recipe prompt improvement
      value:
        messages:
          - role: user
            content:
              - type: text
                text: "Concise recipe for {{food}}"
        feedback: Make the recipes shorter

    ImprovePromptRequestRecipeExample:
      summary: Recipe prompt with example interaction
      value:
        messages:
          - role: user
            content:
              - type: text
                text: "Concise for {{food}}.\n\nexample\n\nmandu: Put the mandu in the air fryer at 380F for 7 minutes."
        system: You are a professional meal prep chef
        feedback: Make it more detailed and include cooking times
        target_model: claude-3-7-sonnet-20250219

    # Improve Prompt Response Examples
    ImprovePromptResponseExample:
      summary: Improved recipe prompt response
      value:
        messages:
          - role: user
            content:
              - type: text
                text: "You are a professional meal prep chef. Create a detailed recipe for {{food}} including preparation time, cooking time, and step-by-step instructions with specific temperatures and timing for each step."
          - role: assistant
            content:
              - type: text
                text: "Here's a detailed recipe for"
        system: ""
        usage:
          input_tokens: 45
          output_tokens: 180

    # Templatize Prompt Request Examples
    TemplatizePromptRequestDefaultExample:
      summary: Simple translation prompt
      value:
        messages:
          - role: user
            content:
              - type: text
                text: Translate hello to German

    TemplatizePromptRequestTranslationExample:
      summary: Translation with system prompt
      value:
        messages:
          - role: user
            content:
              - type: text
                text: Translate hello to German
        system: You are a professional English to German translator

    # Templatize Prompt Response Examples
    TemplatizePromptResponseExample:
      summary: Templatized translation prompt
      value:
        messages:
          - role: user
            content:
              - type: text
                text: "Translate {{WORD_TO_TRANSLATE}} to {{TARGET_LANGUAGE}}"
        system: "You are a professional English to {{TARGET_LANGUAGE}} translator"
        usage:
          input_tokens: 15
          output_tokens: 25
        variable_values:
          WORD_TO_TRANSLATE: hello
          TARGET_LANGUAGE: German

    # Error Examples
    ErrorBadRequestExample:
      summary: Bad request error
      value:
        type: invalid_request_error
        message: Invalid request format

    ErrorUnauthorizedExample:
      summary: Unauthorized error
      value:
        type: authentication_error
        message: Invalid or missing API key

    ErrorForbiddenExample:
      summary: Forbidden error
      value:
        type: permission_error
        message: Access denied or not in closed research preview

    ErrorRateLimitExample:
      summary: Rate limit error
      value:
        type: rate_limit_error
        message: Rate limit exceeded. Please retry after some time.

    ErrorServerExample:
      summary: Server error
      value:
        type: api_error
        message: An internal server error occurred