API Evangelist conversational phrasing for Getemboss Ai Admin API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Getemboss Ai Admin API
  version: 1.0.0
extends: openapi/getemboss-ai-admin-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 43
- target: $.paths['/admin/account'].get
  update:
    x-apievangelist-phrasing:
      intent: View an owner's account and retention default
      effect: read
      questions:
      - What retention default will new forms inherit for this account owner?
      - Can an admin look up who an account owner is and their default retention policy?
      instructions:
      - text: Show the account details and retention default for owner {owner}.
        slots:
          owner: query.owner
      - text: Look up which retention policy new forms for {owner} will inherit.
        slots:
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/account'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change an owner's default retention policy
      effect: write
      questions:
      - How do I change the default retention policy for an account as an admin?
      - Does changing the account retention default affect forms that already exist?
      instructions:
      - text: Update the account default retention for owner {owner}.
        slots:
          owner: query.owner
      - text: Flip the retention default on {owner}'s account so future forms use the new policy.
        slots:
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/usage'].get
  update:
    x-apievangelist-phrasing:
      intent: View usage totals for an owner as admin
      effect: read
      questions:
      - Can an admin see the current usage summary for any account owner?
      - Where does the dashboard get a signed-in owner's usage totals?
      instructions:
      - text: Get the usage summary for owner {owner}.
        slots:
          owner: query.owner
      - text: Show me how much {owner} has used so far as an admin.
        slots:
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/usage/detail'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an owner's detailed usage for a month
      effect: read
      questions:
      - Can I see a detailed usage breakdown for one owner in a specific month?
      - Which month-level usage detail is available for an account?
      instructions:
      - text: Show detailed usage for owner {owner} in month {month}.
        slots:
          owner: query.owner
          month: query.month
      - text: Pull the {month} usage detail for {owner}.
        slots:
          month: query.month
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/billing/breakdown'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an owner's billing breakdown for a month
      effect: read
      questions:
      - What will an owner be billed for in a given month, line by line?
      - Can an admin see the billing breakdown for an account's month?
      instructions:
      - text: Show the billing breakdown for owner {owner} for {month}.
        slots:
          owner: query.owner
          month: query.month
      - text: Break down {owner}'s charges for {month}.
        slots:
          owner: query.owner
          month: query.month
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms'].get
  update:
    x-apievangelist-phrasing:
      intent: List an owner's forms as admin
      effect: read
      questions:
      - Can an admin search through all the forms a particular owner has uploaded?
      - Is there paging when listing an owner's forms from the admin side?
      instructions:
      - text: List the forms owned by {owner}.
        slots:
          owner: query.owner
      - text: Search {owner}'s forms for {q}, returning {limit} at a time.
        slots:
          owner: query.owner
          q: query.q
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a fillable form on behalf of an owner
      effect: write
      questions:
      - How do I create a fillable form for a customer from the admin batch-fill page?
      - Can an admin upload a PDF as a new form billed to another owner?
      instructions:
      - text: Create a fillable form from {file} on behalf of owner {owner}.
        slots:
          file: requestBody.file
          owner: query.owner
      - text: Acting as {owner}, upload this PDF {file} as a new form.
        slots:
          owner: query.owner
          file: requestBody.file
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/batch-runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List an owner's batch-fill runs
      effect: read
      questions:
      - Which batch-fill runs has an owner kicked off?
      - Can an admin page through the history of spreadsheet batch fills for an account?
      instructions:
      - text: List the batch-fill runs for owner {owner}.
        slots:
          owner: query.owner
      - text: Show the last {limit} batch runs for {owner}.
        slots:
          limit: query.limit
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/batch-counts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count an owner's batch-fill runs
      effect: read
      questions:
      - How many batch fills has an owner run in total?
      - Is there a quick count of batch-fill runs per account?
      instructions:
      - text: Get the batch-fill counts for owner {owner}.
        slots:
          owner: query.owner
      - text: Tell me how many batch runs {owner} has.
        slots:
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/layouts'].get
  update:
    x-apievangelist-phrasing:
      intent: Review shared form layout reuse stats
      effect: read
      questions:
      - Which shared form layouts get reused the most, and how many hits do they have?
      - Where can an operator spot layout rows with many loose matches and a low baseline?
      instructions:
      - text: Show the form layout reuse readout.
      - text: List the top {top} most-reused form layouts.
        slots:
          top: query.top
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/{form_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a form's status on behalf of an owner
      effect: read
      questions:
      - Can an admin poll the processing status of a customer's form?
      - Is an owner's uploaded form ready yet, from the admin view?
      instructions:
      - text: Check the status of form {form_id} for owner {owner}.
        slots:
          form_id: path.form_id
          owner: query.owner
      - text: Acting as {owner}, poll whether form {form_id} is ready.
        slots:
          owner: query.owner
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/{form_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an owner's form as admin
      effect: destructive
      questions:
      - Can an admin remove a form from someone else's account?
      - How do I delete a customer's form from the admin dashboard?
      instructions:
      - text: Delete form {form_id} belonging to {owner}.
        slots:
          form_id: path.form_id
          owner: query.owner
      - text: As admin, remove {owner}'s form {form_id}.
        slots:
          owner: query.owner
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/{form_id}/thumbnail'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an owner's form thumbnail as admin
      effect: read
      questions:
      - Can an admin fetch the preview image of a customer's form?
      - What does an owner's form look like as a thumbnail?
      instructions:
      - text: Fetch the thumbnail for form {form_id} owned by {owner}.
        slots:
          form_id: path.form_id
          owner: query.owner
      - text: Show me a preview image of {owner}'s form {form_id}.
        slots:
          owner: query.owner
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/usage/trend'].get
  update:
    x-apievangelist-phrasing:
      intent: Chart an owner's usage trend over days
      effect: read
      questions:
      - How has an owner's usage changed day by day recently?
      - Can I see a usage trend for an account over the last N days?
      instructions:
      - text: Show the daily usage trend for owner {owner}.
        slots:
          owner: query.owner
      - text: Plot {owner}'s usage over the last {days} days.
        slots:
          owner: query.owner
          days: query.days
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/usage/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List an owner's individual usage events
      effect: read
      questions:
      - Which individual billable events did an owner generate?
      - Can I filter an account's usage events by kind and time range?
      instructions:
      - text: List the usage events for owner {owner}.
        slots:
          owner: query.owner
      - text: Show {owner}'s {kinds} usage events in range {range}.
        slots:
          owner: query.owner
          kinds: query.kinds
          range: query.range
      - text: Get page {page} of {owner}'s usage events, {page_size} per page.
        slots:
          page: query.page
          owner: query.owner
          page_size: query.page_size
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/with-context'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a context fill on behalf of an owner
      effect: write
      questions:
      - Can an admin fill a new PDF from supporting context and bill it to a customer?
      - Which admin call powers the /fill page for a given owner?
      instructions:
      - text: Acting as {owner}, fill PDF {file} using context {context}.
        slots:
          owner: query.owner
          file: requestBody.file
          context: requestBody.context
      - text: Start a with-context fill job of {file} for owner {owner}.
        slots:
          file: requestBody.file
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/with-context/{job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an owner's context-fill job status
      effect: read
      questions:
      - Has an owner's context fill job finished yet?
      - Can an admin poll the progress of a with-context fill job?
      instructions:
      - text: Check the status of context-fill job {job_id} for {owner}.
        slots:
          job_id: path.job_id
          owner: query.owner
      - text: Poll {owner}'s with-context job {job_id}.
        slots:
          owner: query.owner
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/with-context/{job_id}/render'].post
  update:
    x-apievangelist-phrasing:
      intent: Render an owner's context-fill job to PDF
      effect: write
      questions:
      - How do I turn a finished context-fill job into a rendered PDF as admin?
      - Can an admin trigger rendering of a customer's context fill?
      instructions:
      - text: Render context-fill job {job_id} for owner {owner}.
        slots:
          job_id: path.job_id
          owner: query.owner
      - text: Acting as {owner}, produce the filled PDF for job {job_id}.
        slots:
          owner: query.owner
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/with-context/{job_id}/pdf'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an owner's context-filled PDF
      effect: read
      questions:
      - Where can an admin download the PDF produced by a customer's context fill?
      - Can I fetch the rendered file from a with-context job for another owner?
      instructions:
      - text: Download the filled PDF from context job {job_id} for {owner}.
        slots:
          job_id: path.job_id
          owner: query.owner
      - text: Get {owner}'s rendered PDF for job {job_id}.
        slots:
          owner: query.owner
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/{form_id}/with-context'].post
  update:
    x-apievangelist-phrasing:
      intent: Fill an owner's existing form from context
      effect: write
      questions:
      - Can an admin fill a form a customer already uploaded using new context?
      - Does filling an existing form from context as admin bill the owner?
      instructions:
      - text: Fill {owner}'s existing form {form_id} from context {context}.
        slots:
          owner: query.owner
          form_id: path.form_id
          context: requestBody.context
      - text: Acting as {owner}, run a context fill on ready form {form_id}.
        slots:
          owner: query.owner
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/web-token/limits'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the engine's upload limits
      effect: read
      questions:
      - What are the maximum upload limits for browser uploads?
      - Where does the website read the engine's file size limits from?
      instructions:
      - text: Show the current web upload limits.
      - text: Fetch the engine's upload limits for the website.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/web-token'].post
  update:
    x-apievangelist-phrasing:
      intent: Mint a short-lived browser upload token
      effect: write
      questions:
      - How does the signed-in browser get a token to upload directly to the owner routes?
      - How long does a minted web upload token last, and can it be refreshed?
      instructions:
      - text: Mint a 15-minute web upload token for owner {owner}.
        slots:
          owner: query.owner
      - text: Issue a browser direct-upload token for {owner}.
        slots:
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/{form_id}/suggest-mapping'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest spreadsheet-to-field mapping for an owner
      effect: write
      questions:
      - Can an admin get suggested column-to-field mappings for a customer's spreadsheet?
      - Is mapping suggestion metered when an admin acts on behalf of an owner?
      instructions:
      - text: Suggest how spreadsheet {file} maps to {owner}'s form {form_id}.
        slots:
          file: requestBody.file
          owner: query.owner
          form_id: path.form_id
      - text: Acting as {owner}, propose column mappings for form {form_id} from {file}.
        slots:
          owner: query.owner
          form_id: path.form_id
          file: requestBody.file
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/{form_id}/fill-batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Batch-fill an owner's form from a spreadsheet
      effect: write
      questions:
      - How do I batch fill a customer's form from a spreadsheet as admin?
      - Is each row billed when an admin runs a batch fill for an owner?
      instructions:
      - text: Batch fill {owner}'s form {form_id} from spreadsheet {file} using mapping {mapping}.
        slots:
          owner: query.owner
          form_id: path.form_id
          file: requestBody.file
          mapping: requestBody.mapping
      - text: Acting as {owner}, fill one copy of form {form_id} per row in {file} with {mapping}.
        slots:
          owner: query.owner
          form_id: path.form_id
          file: requestBody.file
          mapping: requestBody.mapping
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/fill-batch/{batch_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an owner's batch-fill progress
      effect: read
      questions:
      - How far along is a customer's batch fill?
      - Can an admin poll an owner's batch-fill status without being billed?
      instructions:
      - text: Check batch {batch_id} status for owner {owner}.
        slots:
          batch_id: path.batch_id
          owner: query.owner
      - text: Poll {owner}'s batch fill {batch_id}.
        slots:
          owner: query.owner
          batch_id: path.batch_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/forms/fill-batch/{batch_id}/zip'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an owner's batch-fill results as ZIP
      effect: read
      questions:
      - Can an admin download all of a customer's batch-filled PDFs at once?
      - Where is the zip archive of an owner's batch fill?
      instructions:
      - text: Download the zip for batch {batch_id} owned by {owner}.
        slots:
          batch_id: path.batch_id
          owner: query.owner
      - text: Get {owner}'s batch {batch_id} filled PDFs as one archive.
        slots:
          owner: query.owner
          batch_id: path.batch_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/billing/setup-intent'].post
  update:
    x-apievangelist-phrasing:
      intent: Start adding a payment method for an owner
      effect: write
      questions:
      - How do I begin saving a card on file for an account?
      - Can an admin create a billing setup intent for an owner?
      instructions:
      - text: Create a billing setup intent for owner {owner}.
        slots:
          owner: query.owner
      - text: Start payment method setup for {owner}.
        slots:
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/billing/payment-method'].get
  update:
    x-apievangelist-phrasing:
      intent: View an owner's saved payment method
      effect: read
      questions:
      - Which payment method does an account currently have on file?
      - Does this owner have a card saved for billing?
      instructions:
      - text: Show the payment method on file for {owner}.
        slots:
          owner: query.owner
      - text: Check whether owner {owner} has a saved card.
        slots:
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/billing/invoices'].get
  update:
    x-apievangelist-phrasing:
      intent: List an owner's invoices
      effect: read
      questions:
      - What invoices has an account been sent?
      - Can an admin see an owner's past invoices?
      instructions:
      - text: List the invoices for owner {owner}.
        slots:
          owner: query.owner
      - text: Show me {owner}'s billing history invoices.
        slots:
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/billing/confirm'].post
  update:
    x-apievangelist-phrasing:
      intent: Confirm an owner's billing setup
      effect: write
      questions:
      - How do I finish attaching a payment method after the setup intent succeeds?
      - Is there a step to confirm an owner's billing once their card is added?
      instructions:
      - text: Confirm the billing setup for owner {owner}.
        slots:
          owner: query.owner
      - text: Finalize {owner}'s payment method after setup.
        slots:
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/billing/run-invoicing'].post
  update:
    x-apievangelist-phrasing:
      intent: Run the monthly invoicing for a period
      effect: write
      questions:
      - How do I run the monthly billing for all owners?
      - Can I preview invoicing with a dry run before charging anyone?
      - Is it safe to rerun invoicing for the same period twice?
      instructions:
      - text: Run invoicing for period {period}.
        slots:
          period: query.period
      - text: Do a dry run of invoicing for {period} with dry_run {dry_run}.
        slots:
          period: query.period
          dry_run: query.dry_run
      - text: Invoice only owner {owner} for period {period}.
        slots:
          owner: query.owner
          period: query.period
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/nudges/run'].post
  update:
    x-apievangelist-phrasing:
      intent: Run the hourly nudge emails and cleanup
      effect: write
      questions:
      - Which owners would be emailed by the nudge run if I dry-run it?
      - What does the nightly maintenance tick purge besides sending nudges?
      instructions:
      - text: Run the nudge job now.
      - text: Dry-run the nudges for owner {owner} with dry_run {dry_run}.
        slots:
          owner: query.owner
          dry_run: query.dry_run
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/retention/sweep'].post
  update:
    x-apievangelist-phrasing:
      intent: Run the retention and fax cleanup sweep
      effect: destructive
      questions:
      - How are expired documents and stalled faxes cleaned up?
      - Can I see what the retention sweep would delete without touching anything?
      instructions:
      - text: Run the retention sweep.
      - text: Preview the retention sweep with dry_run {dry_run}, capped at {limit} items.
        slots:
          dry_run: query.dry_run
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/library/{slug}/store'].post
  update:
    x-apievangelist-phrasing:
      intent: Store a fetched copy of a library form
      effect: write
      questions:
      - How does the seed script upload a government form into the library catalogue?
      - Which fields does storing a library copy actually trust from the caller?
      instructions:
      - text: Store PDF {file} as library form {slug} with checksum {sha256}.
        slots:
          file: requestBody.file
          slug: path.slug
          sha256: requestBody.sha256
      - text: Save {file} as revision {revision} of library form {slug}, hash {sha256}.
        slots:
          file: requestBody.file
          revision: requestBody.revision
          slug: path.slug
          sha256: requestBody.sha256
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/library/check'].post
  update:
    x-apievangelist-phrasing:
      intent: Run the weekly library freshness check
      effect: write
      questions:
      - How do I check whether any catalogue forms have changed at their source?
      - Does the library freshness check change what is served?
      instructions:
      - text: Run the library freshness check.
      - text: Re-fetch every catalogue form and record whether its hash changed.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/library'].get
  update:
    x-apievangelist-phrasing:
      intent: List catalogue forms with revision and check status
      effect: read
      questions:
      - Which library forms have never been seeded yet?
      - What is the active revision and last check result for each catalogue form?
      instructions:
      - text: Show every library catalogue form with its active revision.
      - text: List catalogue forms still waiting on a seed run.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/library/misses'].get
  update:
    x-apievangelist-phrasing:
      intent: See library searches that found nothing
      effect: read
      questions:
      - Which forms are people searching for that the library doesn't have?
      - What were the most frequent empty library searches recently?
      instructions:
      - text: List the library search misses, most frequent first.
      - text: Show library searches with no result over the last {days} days.
        slots:
          days: query.days
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/library/{slug}/accept'].post
  update:
    x-apievangelist-phrasing:
      intent: Accept a changed library form revision
      effect: write
      questions:
      - How do I promote a changed government form to the active library revision?
      - Is the previous library revision kept when a new one is accepted?
      instructions:
      - text: Accept the changed version of library form {slug}.
        slots:
          slug: path.slug
      - text: Refetch {slug}, make it fillable and set it as the active revision.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/oauth/pending/{pid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a pending OAuth authorization
      effect: read
      questions:
      - What client and scopes is a pending OAuth request asking for?
      - Can I inspect an OAuth authorization that is waiting for consent?
      instructions:
      - text: Show pending OAuth request {pid}.
        slots:
          pid: path.pid
      - text: Look up the details of the OAuth authorization awaiting consent, id {pid}.
        slots:
          pid: path.pid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/oauth/consent'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a user's OAuth consent decision
      effect: write
      questions:
      - How is a user's approve or deny decision on an OAuth app recorded?
      - Can a user deny a pending OAuth client from the consent screen?
      instructions:
      - text: Record decision {decision} from user {user_id} on OAuth request {req}.
        slots:
          decision: requestBody.decision
          user_id: requestBody.user_id
          req: requestBody.req
      - text: Approve OAuth request {req} for user {user_id} with decision {decision}.
        slots:
          req: requestBody.req
          user_id: requestBody.user_id
          decision: requestBody.decision
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/oauth/grants'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's OAuth grants
      effect: read
      questions:
      - Which connected apps has a user granted access to?
      - Can I see all OAuth grants for one user?
      instructions:
      - text: List the OAuth grants for user {user_id}.
        slots:
          user_id: query.user_id
      - text: Show which apps {user_id} has authorized.
        slots:
          user_id: query.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/oauth/clients'].get
  update:
    x-apievangelist-phrasing:
      intent: List OAuth clients registered since a date
      effect: read
      questions:
      - Which directories and gateways have registered as OAuth clients this week?
      - Can I see OAuth client registrations since a specific date for the acquisition report?
      instructions:
      - text: List OAuth clients registered in the last seven days.
      - text: Show OAuth client registrations since {since}.
        slots:
          since: query.since
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/oauth/grants/{gid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a user's OAuth grant
      effect: destructive
      questions:
      - How do I disconnect an app a user previously authorized?
      - Can a single OAuth grant be revoked without affecting the user's other apps?
      instructions:
      - text: Revoke OAuth grant {gid} for user {user_id}.
        slots:
          gid: path.gid
          user_id: query.user_id
      - text: Disconnect app grant {gid} from {user_id}'s account.
        slots:
          gid: path.gid
          user_id: query.user_id
      method: generated
      generated: '2026-10-01'