# 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 Forms API
  version: 1.0.0
extends: openapi/getemboss-ai-forms-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: 27
- target: $.paths['/forms/quote'].post
  update:
    x-apievangelist-phrasing:
      intent: Quote the account price for processing a form
      effect: read
      questions:
      - What would it cost my account to process this PDF before I commit?
      - Can I get a price quote for a form plus supporting context on my account?
      instructions:
      - text: Quote my account price for processing {file}.
        slots:
          file: requestBody.file
      - text: Give me an account quote for {file} filled from context {context}.
        slots:
          file: requestBody.file
          context: requestBody.context
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms'].get
  update:
    x-apievangelist-phrasing:
      intent: List my uploaded forms
      effect: read
      questions:
      - Which forms have I uploaded to my account?
      - Can I filter my forms by processing state, like only the ready ones?
      instructions:
      - text: List my forms.
      - text: Show my forms in state {states}, {limit} at a time.
        slots:
          states: query.states
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a PDF and make it a fillable form
      effect: write
      questions:
      - How do I upload a PDF so Emboss detects its fields?
      - Can I create a form from a library catalogue entry instead of uploading a file?
      - Can I get a callback when my new form finishes extracting?
      instructions:
      - text: Create a form from {file}.
        slots:
          file: requestBody.file
      - text: Create a form from library entry {library} with retention {retention}.
        slots:
          library: requestBody.library
          retention: requestBody.retention
      - text: Upload {file} as a new form and notify {callback_url} when it is ready.
        slots:
          file: requestBody.file
          callback_url: requestBody.callback_url
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/{form_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a form and its processing status
      effect: read
      questions:
      - Is my uploaded form done extracting yet?
      - What do I get back when I look up a single form?
      instructions:
      - text: Get form {form_id}.
        slots:
          form_id: path.form_id
      - text: Check whether form {form_id} is ready.
        slots:
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/{form_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a form and its documents
      effect: destructive
      questions:
      - How do I delete a form and its stored documents?
      - Why would deleting a form return a 409 conflict?
      instructions:
      - text: Delete form {form_id}.
        slots:
          form_id: path.form_id
      - text: Remove form {form_id} and all its documents.
        slots:
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/{form_id}/contract'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a form's field contract
      effect: read
      questions:
      - What fields does my form have and which are required?
      - Can I get the machine-readable field contract for a form?
      instructions:
      - text: Get the field contract for form {form_id}.
        slots:
          form_id: path.form_id
      - text: Show me the detected field schema of {form_id}.
        slots:
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/{form_id}/fillable'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the fillable PDF of a form
      effect: read
      questions:
      - Where do I download the fillable version of a flat PDF I uploaded?
      - Can I get the PDF with fillable fields added back from a form?
      instructions:
      - text: Download the fillable PDF for form {form_id}.
        slots:
          form_id: path.form_id
      - text: Give me the blank fillable version of {form_id}.
        slots:
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/{form_id}/thumbnail'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a form's thumbnail image
      effect: read
      questions:
      - Can I get a small preview image of one of my forms?
      - What does a form's first page look like as a thumbnail?
      instructions:
      - text: Fetch the thumbnail of form {form_id}.
        slots:
          form_id: path.form_id
      - text: Show a preview image for {form_id}.
        slots:
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/with-context'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a new PDF and fill it from context
      effect: write
      questions:
      - Can I upload a blank form and have it filled from my supporting documents in one step?
      - How do I fill a library form from context without uploading the PDF myself?
      instructions:
      - text: Fill new PDF {file} using context {context}.
        slots:
          file: requestBody.file
          context: requestBody.context
      - text: Fill library form {library} from {context} and call {callback_url} when done.
        slots:
          library: requestBody.library
          context: requestBody.context
          callback_url: requestBody.callback_url
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/{form_id}/with-context'].post
  update:
    x-apievangelist-phrasing:
      intent: Fill an existing form from context documents
      effect: write
      questions:
      - How do I fill a form I already uploaded using new supporting documents?
      - Does refilling an existing form from context re-extract its fields or bill extraction again?
      instructions:
      - text: Fill my existing form {form_id} from {context}.
        slots:
          form_id: path.form_id
          context: requestBody.context
      - text: Fill existing form {form_id} from context with policy {policy}.
        slots:
          form_id: path.form_id
          policy: requestBody.policy
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/with-context/{job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a context-fill job's result
      effect: read
      questions:
      - Has my fill-from-context job finished?
      - What did the context fill job produce?
      instructions:
      - text: Check context fill job {job_id}.
        slots:
          job_id: path.job_id
      - text: Get the result of with-context job {job_id}.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/{form_id}/prepare'].post
  update:
    x-apievangelist-phrasing:
      intent: Prepare a fill proposal for an existing form
      effect: write
      questions:
      - Can I review proposed answers for a form I already uploaded before anything is rendered?
      - What's the difference between preparing a form and filling it directly?
      instructions:
      - text: Prepare a proposal for existing form {form_id} from {context}.
        slots:
          form_id: path.form_id
          context: requestBody.context
      - text: Draft proposed answers for form {form_id} without rendering a PDF.
        slots:
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/prepare'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a PDF and prepare a fill proposal
      effect: write
      questions:
      - Can I upload a new PDF and get proposed answers to review in a single call?
      - How do I get a proposal for a brand new form from my context documents?
      instructions:
      - text: Extract {file} and prepare a proposal from {context}.
        slots:
          file: requestBody.file
          context: requestBody.context
      - text: Upload new PDF {file} and draft answers for review.
        slots:
          file: requestBody.file
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/{form_id}/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Check whether a filled PDF is complete
      effect: read
      questions:
      - Is this filled PDF actually done, or are fields still missing?
      - Can I verify a form I filled by hand against its field contract?
      instructions:
      - text: Verify filled PDF {file} against form {form_id}.
        slots:
          file: requestBody.file
          form_id: path.form_id
      - text: Check if {file} completes every required field of {form_id}.
        slots:
          file: requestBody.file
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/{form_id}/preview-fill'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview how a form would be filled
      effect: read
      questions:
      - Can I see what values would go into a form before filling it for real?
      - Can I lock certain fields when previewing a fill?
      instructions:
      - text: Preview filling form {form_id} from {context}.
        slots:
          form_id: path.form_id
          context: requestBody.context
      - text: Preview a fill of {form_id} keeping fields {locked} locked.
        slots:
          form_id: path.form_id
          locked: requestBody.locked
      - text: Preview {form_id} for only the fields {asked_field_ids}.
        slots:
          form_id: path.form_id
          asked_field_ids: requestBody.asked_field_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/{form_id}/suggest-mapping'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest spreadsheet columns for form fields
      effect: write
      questions:
      - Which spreadsheet columns match which fields on my form?
      - Can Emboss guess the column mapping before I run a batch fill?
      instructions:
      - text: Suggest a column mapping from {file} to form {form_id}.
        slots:
          file: requestBody.file
          form_id: path.form_id
      - text: Match the columns in spreadsheet {file} to the fields of {form_id}.
        slots:
          file: requestBody.file
          form_id: path.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/{form_id}/fill-batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Batch-fill a form from a spreadsheet
      effect: write
      questions:
      - How do I fill one copy of a form for every row of a spreadsheet?
      - Am I billed per row when batch filling?
      instructions:
      - text: Batch fill form {form_id} from {file} using mapping {mapping}.
        slots:
          form_id: path.form_id
          file: requestBody.file
          mapping: requestBody.mapping
      - text: Generate a filled {form_id} for each row of {file} with column mapping {mapping}.
        slots:
          form_id: path.form_id
          file: requestBody.file
          mapping: requestBody.mapping
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/fill-batch/{batch_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a batch fill's progress
      effect: read
      questions:
      - How many rows of my batch fill are done?
      - Did any rows in my spreadsheet batch fail?
      instructions:
      - text: Check the status of batch {batch_id}.
        slots:
          batch_id: path.batch_id
      - text: Show row-by-row progress for batch fill {batch_id}.
        slots:
          batch_id: path.batch_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/fill-batch/{batch_id}/rows/{n}/pdf'].get
  update:
    x-apievangelist-phrasing:
      intent: Download one row's PDF from a batch fill
      effect: read
      questions:
      - Can I download the filled PDF for just one spreadsheet row?
      - Where is the output for a single row of a batch?
      instructions:
      - text: Download the PDF for row {n} of batch {batch_id}.
        slots:
          n: path.n
          batch_id: path.batch_id
      - text: Get batch {batch_id}'s filled form for row number {n}.
        slots:
          batch_id: path.batch_id
          n: path.n
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/fill-batch/{batch_id}/zip'].get
  update:
    x-apievangelist-phrasing:
      intent: Download all batch-filled PDFs as a ZIP
      effect: read
      questions:
      - Can I download every filled PDF from a batch in one archive?
      - Is there a zip file of all my batch results?
      instructions:
      - text: Download the zip for batch {batch_id}.
        slots:
          batch_id: path.batch_id
      - text: Bundle every filled PDF from batch {batch_id} into one archive.
        slots:
          batch_id: path.batch_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forms/read'].post
  update:
    x-apievangelist-phrasing:
      intent: Read values out of a filled PDF on my account
      effect: read
      questions:
      - Can I extract the answers from a filled PDF using my account key?
      - Will reading a filled PDF against one of my forms tell me if it's complete?
      instructions:
      - text: Read the field values from {file}.
        slots:
          file: requestBody.file
      - text: Read {file} as a filled copy of my form {form_id}.
        slots:
          file: requestBody.file
          form_id: requestBody.form_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/pay/make-fillable'].post
  update:
    x-apievangelist-phrasing:
      intent: Pay per use to make a flat PDF fillable
      effect: write
      questions:
      - Can I turn a scanned PDF into a fillable form without an account by paying per use?
      - Does the pay-per-use make-fillable work on XFA or LiveCycle forms?
      instructions:
      - text: Pay to make {file} fillable.
        slots:
          file: requestBody.file
      - text: Add fillable fields to the PDF at {pdf_url} on the pay door.
        slots:
          pdf_url: requestBody.pdf_url
      method: generated
      generated: '2026-10-01'
- target: $.paths['/pay/fill-with-context'].post
  update:
    x-apievangelist-phrasing:
      intent: Pay per use to fill a PDF from documents
      effect: write
      questions:
      - Can I pay per use to pre-fill a government form from a resume or supporting paperwork?
      - 'Which context inputs can a paid fill-with-context accept: files, text or URLs?'
      instructions:
      - text: Pay to fill {file} from context documents {context}.
        slots:
          file: requestBody.file
          context: requestBody.context
      - text: Pay to fill the PDF at {pdf_url} using notes {context_text}.
        slots:
          pdf_url: requestBody.pdf_url
          context_text: requestBody.context_text
      - text: Fill {file} from the pages at {context_urls} in pay-per-use mode {mode}.
        slots:
          file: requestBody.file
          context_urls: requestBody.context_urls
          mode: requestBody.mode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/pay/fill'].post
  update:
    x-apievangelist-phrasing:
      intent: Pay per use to fill a PDF from JSON values
      effect: write
      questions:
      - Can I fill a PDF with answers I already have as JSON, paying per use?
      - What shape should the values be in for a paid structured fill?
      instructions:
      - text: Pay to fill {file} with values {values}.
        slots:
          file: requestBody.file
          values: requestBody.values
      - text: Write the answers {values} into the PDF at {pdf_url} on the pay door.
        slots:
          values: requestBody.values
          pdf_url: requestBody.pdf_url
      method: generated
      generated: '2026-10-01'
- target: $.paths['/pay/read'].post
  update:
    x-apievangelist-phrasing:
      intent: Pay per use to read a filled PDF into data
      effect: read
      questions:
      - Can I turn a filled PDF into JSON without signing up, paying per use?
      - Does the paid read tell me whether a known form is complete?
      instructions:
      - text: Pay to read the answers out of {file}.
        slots:
          file: requestBody.file
      - text: Extract field values from the filled PDF at {pdf_url} via the pay door.
        slots:
          pdf_url: requestBody.pdf_url
      method: generated
      generated: '2026-10-01'
- target: $.paths['/pay/fax'].post
  update:
    x-apievangelist-phrasing:
      intent: Pay per page to fax a PDF
      effect: write
      questions:
      - Can an agent fax a PDF to an agency and pay per transmitted page?
      - Is there a minimum charge when paying for a fax by card?
      instructions:
      - text: Pay to fax {file} to {to}.
        slots:
          file: requestBody.file
          to: requestBody.to
      - text: Fax artifact {artifact_id} to {to} using artifact token {artifact_token}.
        slots:
          artifact_id: requestBody.artifact_id
          to: requestBody.to
          artifact_token: requestBody.artifact_token
      method: generated
      generated: '2026-10-01'
- target: $.paths['/pay/quote'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a free price check for a PDF
      effect: read
      questions:
      - How much will each operation cost for this PDF before I pay?
      - Does the free quote tell me whether my PDF already has form fields?
      instructions:
      - text: Get a free price check for {file}.
        slots:
          file: requestBody.file
      - text: Quote every operation's price for the PDF at {pdf_url} with context {context_text}.
        slots:
          pdf_url: requestBody.pdf_url
          context_text: requestBody.context_text
      method: generated
      generated: '2026-10-01'