# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clerk Platform Applications API
  version: 1.0.0
extends: openapi/clerk-com-applications-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 11
- target: $.paths['/platform/applications'].get
  update:
    x-apievangelist-phrasing:
      intent: List my Clerk applications
      effect: read
      questions:
      - Which applications exist in my Clerk workspace?
      - Can I get the secret keys for all my applications in one listing?
      instructions:
      - text: List all applications in my workspace.
      - text: List my applications including their secret keys.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new application
      effect: write
      questions:
      - How do I spin up a new Clerk application programmatically?
      - Can I choose environment types or a template when creating an application?
      instructions:
      - text: Create an application named {name}.
        slots:
          name: requestBody.name
      - text: Create application {name} on production domain {domain}.
        slots:
          name: requestBody.name
          domain: requestBody.domain
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an application's details
      effect: read
      questions:
      - What instances and settings does one of my applications have?
      - Can I fetch a single application together with its secret keys?
      instructions:
      - text: Get details for application {applicationID}.
        slots:
          applicationID: path.applicationID
      - text: Show application {applicationID} with its secret keys included.
        slots:
          applicationID: path.applicationID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an application
      effect: destructive
      questions:
      - How do I permanently delete an application from my workspace?
      - What happens to an application's instances when I delete it?
      instructions:
      - text: Delete application {applicationID}.
        slots:
          applicationID: path.applicationID
      - text: Permanently remove application {applicationID} from my workspace.
        slots:
          applicationID: path.applicationID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename an application
      effect: write
      questions:
      - How do I rename an existing application?
      - Which application properties can I change after creating it?
      instructions:
      - text: Rename application {applicationID} to {name}.
        slots:
          applicationID: path.applicationID
          name: requestBody.name
      - text: Update the display name of {applicationID} to {name}.
        slots:
          applicationID: path.applicationID
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}/logo'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload an application's logo
      effect: write
      questions:
      - How do I set the logo shown on my application's sign-in screens?
      - Can I replace an application's existing logo with a new image file?
      instructions:
      - text: Upload {file} as the logo for application {applicationID}.
        slots:
          file: requestBody.file
          applicationID: path.applicationID
      - text: Replace the logo of {applicationID} with image {file}.
        slots:
          file: requestBody.file
          applicationID: path.applicationID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}/logo'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an application's logo
      effect: destructive
      questions:
      - How do I remove the logo from an application?
      - Can I clear an application's logo without uploading a replacement?
      instructions:
      - text: Delete the logo of application {applicationID}.
        slots:
          applicationID: path.applicationID
      - text: Remove the uploaded logo from {applicationID}.
        slots:
          applicationID: path.applicationID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}/favicon'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload an application's favicon
      effect: write
      questions:
      - How do I set the favicon for my application?
      - Can I swap out an application's favicon by uploading a new image?
      instructions:
      - text: Upload {file} as the favicon for application {applicationID}.
        slots:
          file: requestBody.file
          applicationID: path.applicationID
      - text: Replace the favicon of {applicationID} with {file}.
        slots:
          file: requestBody.file
          applicationID: path.applicationID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}/favicon'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an application's favicon
      effect: destructive
      questions:
      - How do I delete the favicon from an application?
      - Can I go back to having no favicon on my application?
      instructions:
      - text: Delete the favicon of application {applicationID}.
        slots:
          applicationID: path.applicationID
      - text: Remove the uploaded favicon from {applicationID}.
        slots:
          applicationID: path.applicationID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}/instances/{envOrInsID}/usage'].get
  update:
    x-apievangelist-phrasing:
      intent: Get usage totals for an application instance
      effect: read
      questions:
      - How many monthly active users and organizations did my production instance use?
      - Can I see SMS and enterprise connection usage for an instance over a date range?
      instructions:
      - text: Get usage for the {envOrInsID} instance of application {applicationID}.
        slots:
          envOrInsID: path.envOrInsID
          applicationID: path.applicationID
      - text: Show MAU and SMS usage for {applicationID} {envOrInsID} from {start} to {end}.
        slots:
          envOrInsID: path.envOrInsID
          applicationID: path.applicationID
          start: query.start
          end: query.end
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/accountless_applications/claim'].post
  update:
    x-apievangelist-phrasing:
      intent: Claim an accountless application into my workspace
      effect: write
      questions:
      - How do I take ownership of an app that was created without an account?
      - Is an accountless application claim token reusable after it's claimed?
      instructions:
      - text: Claim the accountless application with token {token} and name it {name}.
        slots:
          token: requestBody.token
          name: requestBody.name
      - text: Move accountless app claim {token} into my workspace as {name}.
        slots:
          token: requestBody.token
          name: requestBody.name
      method: generated
      generated: '2026-09-26'