# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OpenMercantil User API
  version: 1.0.0
extends: openapi/openmercantil-user-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: 65
- target: $.paths['/api/v1/user/me'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my account profile and plan
      effect: read
      questions:
      - Which plan tier is my OpenMercantil account on?
      - Where do I get a fresh CSRF token together with my user profile?
      instructions:
      - text: Show my account profile, plan and persona.
      - text: Tell me whether my account has finished onboarding.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/org'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my organization, seats and members
      effect: read
      questions:
      - Which team members and seats does my organization have?
      - Can I create a team on my current plan if I don't belong to an organization yet?
      instructions:
      - text: Show my organization with its seats and visible members.
      - text: List the people in my team.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/org'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename my organization
      effect: write
      questions:
      - How do I change the name of my organization?
      - Who is allowed to rename the organization?
      instructions:
      - text: Rename my organization to {name}.
        slots:
          name: requestBody.name
      - text: Change our team's display name to {name}.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/org'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization
      effect: write
      questions:
      - Can I set up a team organization on a MAX or Enterprise plan?
      - What happens to my role when I start a new organization?
      instructions:
      - text: Create a new organization called {name} with me as owner.
        slots:
          name: requestBody.name
      - text: Start a team named {name}.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/org/invites'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite someone to my organization
      effect: write
      questions:
      - How do I invite a colleague to join my organization?
      - Is there a daily limit on organization invitations or a seat cap?
      instructions:
      - text: Invite {email} to my organization.
        slots:
          email: requestBody.email
      - text: Invite {email} to the team as {role}.
        slots:
          email: requestBody.email
          role: requestBody.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/org/invites/{id}/resend'].post
  update:
    x-apievangelist-phrasing:
      intent: Resend an organization invitation
      effect: write
      questions:
      - My colleague lost their invite email; can I send the organization invitation again?
      - Does resending an invitation invalidate the old invite link?
      instructions:
      - text: Resend organization invitation {id}.
        slots:
          id: path.id
      - text: Rotate the token on invite {id} and email it again.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/org/invites/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel a pending organization invitation
      effect: destructive
      questions:
      - How do I withdraw an invitation that hasn't been accepted yet?
      - Can an admin cancel a pending team invite?
      instructions:
      - text: Cancel pending invitation {id}.
        slots:
          id: path.id
      - text: Withdraw the team invite {id} before it's accepted.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/org/members/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a team member's role
      effect: write
      questions:
      - How do I promote a team member to admin?
      - Can the organization owner's own role be changed?
      instructions:
      - text: Change member {id}'s role to {role}.
        slots:
          id: path.id
          role: requestBody.role
      - text: Make organization member {id} a {role}.
        slots:
          id: path.id
          role: requestBody.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/org/members/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a member from my organization
      effect: destructive
      questions:
      - How do I remove someone from my organization?
      - Can an admin remove another admin or the owner?
      instructions:
      - text: Remove member {id} from the organization.
        slots:
          id: path.id
      - text: Kick {id} off our team.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/org/leave'].post
  update:
    x-apievangelist-phrasing:
      intent: Leave my current organization
      effect: destructive
      questions:
      - How do I leave the organization I belong to?
      - Can an owner leave the organization without transferring ownership first?
      instructions:
      - text: Take me out of my current organization.
      - text: Leave the organization using CSRF token {csrf_token}.
        slots:
          csrf_token: header.X-CSRF-Token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/persona'].get
  update:
    x-apievangelist-phrasing:
      intent: See my persona and the available personas
      effect: read
      questions:
      - Which persona is my account set to?
      - What personas can I choose from?
      instructions:
      - text: Show my current persona and the list I can pick from.
      - text: List the available account personas.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/persona'].post
  update:
    x-apievangelist-phrasing:
      intent: Set my primary persona
      effect: write
      questions:
      - How do I switch my account to a different persona?
      - Which values are valid when setting my primary persona?
      instructions:
      - text: Set my primary persona to {persona}.
        slots:
          persona: requestBody.persona
      - text: Switch my account persona to {persona}.
        slots:
          persona: requestBody.persona
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List my saved company segments
      effect: read
      questions:
      - Which saved company segments have I built?
      - Can I show only my pinned segments?
      instructions:
      - text: List my saved segments.
      - text: Show my segments filtered by pinned = {pinned}, up to {limit}.
        slots:
          pinned: query.pinned
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a new company segment
      effect: write
      questions:
      - How do I save a reusable filter of companies by province or CNAE prefix?
      - What filter anchor does a new segment need, and why would it be rejected with 422?
      instructions:
      - text: Create a segment called {name} with filters {filters}.
        slots:
          name: requestBody.name
          filters: requestBody.filters
      - text: Save segment {name}, described as {description}, using filters {filters}, and pin it.
        slots:
          name: requestBody.name
          description: requestBody.description
          filters: requestBody.filters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/segments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one saved segment
      effect: read
      questions:
      - What filters are stored in one of my segments?
      - Can I look up a single segment's definition by its id?
      instructions:
      - text: Get segment {id}.
        slots:
          id: path.id
      - text: Show the filters saved in segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/segments/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a segment's editable fields
      effect: write
      questions:
      - How do I overwrite a segment's name, description and filters all at once?
      - Can I fully replace an existing segment definition?
      instructions:
      - text: Replace segment {id} with name {name} and filters {filters_json}.
        slots:
          id: path.id
          name: requestBody.name
          filters_json: requestBody.filters_json
      - text: Overwrite all mutable fields of segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/segments/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a saved segment
      effect: destructive
      questions:
      - How do I get rid of a segment I no longer use?
      - Is deleting a saved segment permanent?
      instructions:
      - text: Delete segment {id}.
        slots:
          id: path.id
      - text: Remove the saved company segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/segments/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit selected fields of a segment
      effect: write
      questions:
      - Can I tweak just one field of a segment, like its icon, without resending the rest?
      - How do I rename a segment and leave its filters untouched?
      instructions:
      - text: Rename segment {id} to {name}, leaving the other fields as they are.
        slots:
          id: path.id
          name: requestBody.name
      - text: Change only the icon of segment {id} to {icon}.
        slots:
          id: path.id
          icon: requestBody.icon
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/segments/{id}/pin'].post
  update:
    x-apievangelist-phrasing:
      intent: Pin or unpin a segment
      effect: write
      questions:
      - How do I pin a segment to the top of my list?
      - Does the pin action toggle, so calling it again unpins?
      instructions:
      - text: Toggle the pin on segment {id}.
        slots:
          id: path.id
      - text: Unpin segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/segments/{id}/run'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a segment to get matching companies
      effect: read
      questions:
      - Which companies match my saved segment right now?
      - What's the most companies a segment run can return, and is the count a global total?
      instructions:
      - text: Run segment {id} and return the matching companies.
        slots:
          id: path.id
      - text: Execute segment {id}, capped at {limit} companies.
        slots:
          id: path.id
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List my saved lists
      effect: read
      questions:
      - What lists of companies and people have I saved?
      - Where can I see all my watchlists at once?
      instructions:
      - text: Show all my lists.
      - text: List my saved watchlists.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a list
      effect: write
      questions:
      - How do I start a new watchlist to track companies?
      - Can I give a new list a color and a kind?
      instructions:
      - text: Create a list named {name}.
        slots:
          name: requestBody.name
      - text: Create a {kind} list called {name} colored {color}.
        slots:
          kind: requestBody.kind
          name: requestBody.name
          color: requestBody.color
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/lists/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a list and its items
      effect: read
      questions:
      - Which companies are inside one of my lists?
      - Can I open a single list with all its entries?
      instructions:
      - text: Get list {id} with its items.
        slots:
          id: path.id
      - text: Show everything saved in list {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/lists/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a list's editable fields
      effect: write
      questions:
      - How do I overwrite a list's name, description, color and kind in one go?
      - Can I fully replace the settings of an existing list?
      instructions:
      - text: Replace list {id} settings with name {name}, color {color} and kind {kind}.
        slots:
          id: path.id
          name: requestBody.name
          color: requestBody.color
          kind: requestBody.kind
      - text: Overwrite all mutable fields on list {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/lists/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a list and its items
      effect: destructive
      questions:
      - What happens to the items when I delete a list?
      - How do I remove an entire watchlist?
      instructions:
      - text: Delete list {id} along with its items.
        slots:
          id: path.id
      - text: Remove watchlist {id} entirely.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/lists/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit selected fields of a list
      effect: write
      questions:
      - Can I just recolor a list without touching its name?
      - How do I rename a list while keeping its other settings?
      instructions:
      - text: Change only the color of list {id} to {color}.
        slots:
          id: path.id
          color: requestBody.color
      - text: Rename list {id} to {name} and keep everything else.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/lists/{id}/items'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a company or person to a list
      effect: write
      questions:
      - How do I add a company to one of my watchlists?
      - Can I attach a note when adding an item to a list?
      instructions:
      - text: Add {type} {slug} to list {id}.
        slots:
          type: requestBody.type
          slug: requestBody.slug
          id: path.id
      - text: Put company {slug} on list {id} with the note {note}.
        slots:
          slug: requestBody.slug
          id: path.id
          note: requestBody.note
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/lists/{id}/items/{item_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an item from a list
      effect: destructive
      questions:
      - How do I take a single company off a list without deleting the list?
      - Can I drop one entry from a watchlist?
      instructions:
      - text: Remove item {item_id} from list {id}.
        slots:
          item_id: path.item_id
          id: path.id
      - text: Drop entry {item_id} off watchlist {id}.
        slots:
          item_id: path.item_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/notes'].get
  update:
    x-apievangelist-phrasing:
      intent: List my recent notes
      effect: read
      questions:
      - What are the latest private notes I've written?
      - Can I limit how many recent notes come back?
      instructions:
      - text: Show my recent notes.
      - text: List my {limit} most recent notes.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/notes'].post
  update:
    x-apievangelist-phrasing:
      intent: Write a private note on a company or person
      effect: write
      questions:
      - How do I jot down a private note about a company?
      - Can I pin a note I attach to a person?
      instructions:
      - text: Add a private note to {target_type} {target_id} saying {body}.
        slots:
          target_type: requestBody.target_type
          target_id: requestBody.target_id
          body: requestBody.body
      - text: 'Create a note titled {title} on {target_type} {target_id}: {body}.'
        slots:
          title: requestBody.title
          target_type: requestBody.target_type
          target_id: requestBody.target_id
          body: requestBody.body
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/notes/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one note
      effect: read
      questions:
      - Can I open a single note by its id?
      - How do I read the full text of one of my notes?
      instructions:
      - text: Get note {id}.
        slots:
          id: path.id
      - text: Show me the full body of note {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/notes/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a note's title, body and pin
      effect: write
      questions:
      - How do I rewrite a note completely, title and body together?
      - Can I overwrite every editable field of a note at once?
      instructions:
      - text: Replace note {id} with title {title} and body {body}.
        slots:
          id: path.id
          title: requestBody.title
          body: requestBody.body
      - text: Overwrite all editable fields of note {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/notes/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a note
      effect: destructive
      questions:
      - How do I delete a private note?
      - Can I permanently remove a note I wrote on a company?
      instructions:
      - text: Delete note {id}.
        slots:
          id: path.id
      - text: Erase my note {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/notes/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit selected fields of a note
      effect: write
      questions:
      - Can I pin a note without resending its text?
      - How do I fix just the title of a note?
      instructions:
      - text: Set pinned to {pinned} on note {id} and leave the text alone.
        slots:
          pinned: requestBody.pinned
          id: path.id
      - text: Change only the title of note {id} to {title}.
        slots:
          id: path.id
          title: requestBody.title
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/notes/for/{type}/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my notes about a company or person
      effect: read
      questions:
      - What notes have I written about a particular company?
      - Can I pull every note attached to one person?
      instructions:
      - text: Show all my notes about {type} {id}.
        slots:
          type: path.type
          id: path.id
      - text: List notes attached to company {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List my tags with usage counts
      effect: read
      questions:
      - Which tags have I created and how many items use each?
      - Where can I see my tag counts?
      instructions:
      - text: List my tags with counts.
      - text: Show how many items carry each of my tags.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a tag
      effect: write
      questions:
      - How do I make a new tag to label companies?
      - Is the number of tags I can create limited by plan?
      instructions:
      - text: Create a tag named {name}.
        slots:
          name: requestBody.name
      - text: Make a {color} tag called {name}.
        slots:
          color: requestBody.color
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/tags/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tag and its assignments
      effect: destructive
      questions:
      - If I delete a tag, is it removed from everything it was applied to?
      - How do I delete one of my tags?
      instructions:
      - text: Delete tag {id}.
        slots:
          id: path.id
      - text: Remove tag {id} and all of its assignments.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/tags/{id}/assign'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply a tag to a company or person
      effect: write
      questions:
      - How do I label a company with one of my tags?
      - Can I tag a person as well as a company?
      instructions:
      - text: Apply tag {id} to {target_type} {target_id}.
        slots:
          id: path.id
          target_type: requestBody.target_type
          target_id: requestBody.target_id
      - text: Tag company {target_id} with tag {id}.
        slots:
          target_id: requestBody.target_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/tags/{id}/unassign'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a tag from a company or person
      effect: write
      questions:
      - How do I take a tag off a company without deleting the tag?
      - Can I untag a single person?
      instructions:
      - text: Unassign tag {id} from {target_type} {target_id}.
        slots:
          id: path.id
          target_type: requestBody.target_type
          target_id: requestBody.target_id
      - text: Strip tag {id} off company {target_id}.
        slots:
          id: path.id
          target_id: requestBody.target_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/exports'].get
  update:
    x-apievangelist-phrasing:
      intent: See my export history and monthly usage
      effect: read
      questions:
      - Which exports have I run recently?
      - Can I see past exports alongside how much of this month's quota I've used?
      instructions:
      - text: Show my export history.
      - text: List my last {limit} exports with this month's usage.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/exports/usage'].get
  update:
    x-apievangelist-phrasing:
      intent: Check my monthly export quota
      effect: read
      questions:
      - How many exports do I have left this month?
      - What's my monthly export quota usage, without the history?
      instructions:
      - text: Check my monthly export quota usage.
      - text: Tell me how much of my export allowance remains.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/audit'].get
  update:
    x-apievangelist-phrasing:
      intent: View my account audit log
      effect: read
      questions:
      - Which plans include the account audit log, and how long is it kept?
      - Can I see who did what in my account?
      instructions:
      - text: Show my account audit log.
      - text: Get {limit} audit entries starting at offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/persons/lookup'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a KYC lookup by DNI/NIE
      effect: read
      questions:
      - Can I run a KYC check on someone using their DNI or NIE?
      - Do I have to declare a legitimate purpose before a documentary person lookup?
      instructions:
      - text: Run a KYC lookup on DNI/NIE {dni_or_nie} for the purpose {finalidad}.
        slots:
          dni_or_nie: requestBody.dni_or_nie
          finalidad: requestBody.finalidad
      - text: 'Look up identity document {dni_or_nie}; stated purpose: {finalidad}.'
        slots:
          dni_or_nie: requestBody.dni_or_nie
          finalidad: requestBody.finalidad
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/persons/lookup/usage'].get
  update:
    x-apievangelist-phrasing:
      intent: Check my KYC lookup allowance
      effect: read
      questions:
      - How many KYC lookups does my plan allow and how many have I used?
      - Is my tier eligible for DNI lookups at all?
      instructions:
      - text: Check my KYC lookup allowance and usage.
      - text: Tell me how many DNI lookups I have left.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/persons/lookup/history'].get
  update:
    x-apievangelist-phrasing:
      intent: See my past KYC lookups
      effect: read
      questions:
      - Which KYC lookups have I run before?
      - Are identifiers masked in my lookup history?
      instructions:
      - text: Show my redacted KYC lookup history.
      - text: List {limit} past KYC lookups from offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/api-credentials'].get
  update:
    x-apievangelist-phrasing:
      intent: List my API credentials
      effect: read
      questions:
      - Which API keys exist on my account and what scopes do they have?
      - Can I see an API key's prefix and last four characters without the secret?
      instructions:
      - text: List my API credentials.
      - text: Page through my API keys, {limit} at a time from cursor {cursor}.
        slots:
          limit: query.limit
          cursor: query.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/api-credentials'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an API credential
      effect: write
      questions:
      - How do I generate a new API key?
      - What is the longest expiry I can set on a new API credential?
      instructions:
      - text: Create an API credential named {name} with scopes {scopes}.
        slots:
          name: requestBody.name
          scopes: requestBody.scopes
      - text: Issue a new API key scoped to {scopes} expiring {expires_at}.
        slots:
          scopes: requestBody.scopes
          expires_at: requestBody.expires_at
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/api-credentials/{id}/rotate'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate an API credential
      effect: destructive
      questions:
      - How do I swap a compromised API key for a new token?
      - Does rotating an API key revoke the old one?
      instructions:
      - text: Rotate API credential {id}.
        slots:
          id: path.id
      - text: Rotate key {id} and give the replacement the scopes {scopes}.
        slots:
          id: path.id
          scopes: requestBody.scopes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/api-credentials/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke an API credential
      effect: destructive
      questions:
      - How do I permanently disable an API key?
      - Can I revoke a key without getting a replacement token?
      instructions:
      - text: Revoke API credential {id}.
        slots:
          id: path.id
      - text: Disable API key {id} for good.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/webhooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List my outbound webhooks
      effect: read
      questions:
      - Which webhooks have I registered and which event types are allowed?
      - Is the webhook delivery worker healthy?
      instructions:
      - text: List my outbound webhooks.
      - text: Show the webhook event allowlist and worker health.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/webhooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Register an outbound webhook
      effect: write
      questions:
      - How do I get notified at my own HTTPS endpoint when registry events happen?
      - Can a webhook subscribe to wildcard events?
      instructions:
      - text: Create a webhook to {url} for events {events}.
        slots:
          url: requestBody.url
          events: requestBody.events
      - text: Send {events} notifications to my endpoint {url}.
        slots:
          events: requestBody.events
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/webhooks/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an outbound webhook
      effect: destructive
      questions:
      - How do I stop and remove a webhook for good?
      - Can I delete a webhook I no longer need?
      instructions:
      - text: Delete webhook {id}.
        slots:
          id: path.id
      - text: Remove outbound webhook {id} permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/webhooks/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a webhook's URL, events or status
      effect: write
      questions:
      - How do I point an existing webhook at a new URL?
      - Can I pause a webhook without deleting it?
      instructions:
      - text: Change webhook {id} to deliver to {url}.
        slots:
          id: path.id
          url: requestBody.url
      - text: Set webhook {id} active to {active}.
        slots:
          id: path.id
          active: requestBody.active
      - text: Subscribe webhook {id} to events {events}.
        slots:
          id: path.id
          events: requestBody.events
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/user/webhooks/{id}/rotate'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate a webhook's signing secret
      effect: destructive
      questions:
      - How do I get a new signing secret for a webhook?
      - What happens to pending deliveries signed with the old webhook secret?
      instructions:
      - text: Rotate the signing secret for webhook {id}.
        slots:
          id: path.id
      - text: Issue a fresh signature key on webhook {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/support/ticket/{id}/reply'].post
  update:
    x-apievangelist-phrasing:
      intent: Reply to my support ticket
      effect: write
      questions:
      - How do I add a reply to a support ticket I opened?
      - Can I reply to a support ticket that's already closed?
      instructions:
      - text: 'Reply to ticket {id}: {body}.'
        slots:
          id: path.id
          body: requestBody.body
      - text: Post {body} on my support ticket {id}.
        slots:
          body: requestBody.body
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/csrf'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a CSRF token for my session
      effect: read
      questions:
      - Where do I get a CSRF token before making an account change?
      - Is my browser session currently authenticated?
      instructions:
      - text: Get a fresh CSRF token.
      - text: Check whether my session is logged in and fetch its CSRF token.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/resend-verification'].post
  update:
    x-apievangelist-phrasing:
      intent: Resend my email verification link
      effect: write
      questions:
      - I never got the verification email; can it be sent again?
      - Is resending the verification link rate-limited?
      instructions:
      - text: Resend my account verification email.
      - text: Send the email-verification link again with CSRF token {csrf_token}.
        slots:
          csrf_token: header.X-CSRF-Token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/credits/checkout'].post
  update:
    x-apievangelist-phrasing:
      intent: Buy a credit pack
      effect: write
      questions:
      - How do I buy more credits?
      - Is a retry of a credit-pack checkout safe from double charging?
      instructions:
      - text: Start checkout for credit pack {pack}.
        slots:
          pack: requestBody.pack
      - text: Buy the {pack} credit pack.
        slots:
          pack: requestBody.pack
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/empresa/{slug}/informe-legal'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a redacted legal report on a company
      effect: write
      questions:
      - Can I get a legal report on a Spanish company using my credits?
      - Is the company legal report legal advice or an official certificate?
      instructions:
      - text: Generate the legal report for company {slug}.
        slots:
          slug: path.slug
      - text: Spend credits on a redacted informe legal for {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/checkout'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a subscription checkout
      effect: write
      questions:
      - How do I upgrade to a paid plan?
      - Can I pay annually and apply a coupon when subscribing?
      instructions:
      - text: Start a subscription checkout for the {plan} plan.
        slots:
          plan: requestBody.plan
      - text: Subscribe me to {plan} billed {billing} with coupon {coupon}.
        slots:
          plan: requestBody.plan
          billing: requestBody.billing
          coupon: requestBody.coupon
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billing/invoices'].get
  update:
    x-apievangelist-phrasing:
      intent: List my invoices and subscription
      effect: read
      questions:
      - Where can I download my past invoices?
      - What subscription am I currently paying for?
      instructions:
      - text: List my invoices.
      - text: Show my current subscription and billing history.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billing/portal'].get
  update:
    x-apievangelist-phrasing:
      intent: Open my Stripe billing portal
      effect: read
      questions:
      - How do I get to the Stripe portal to change my card?
      - Is there a link that redirects me straight to my billing portal?
      instructions:
      - text: Redirect me to my Stripe billing portal.
      - text: Take me to the page where I manage my payment method.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/billing/portal'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Stripe portal session URL
      effect: write
      questions:
      - Can I get the Stripe portal session as JSON instead of a redirect?
      - Which endpoint should a new client use to create a billing portal session?
      instructions:
      - text: Create a billing portal session and return its URL as JSON.
      - text: Create a Stripe portal session with CSRF token {csrf_token}.
        slots:
          csrf_token: header.X-CSRF-Token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/portal'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a portal session via the legacy alias
      effect: write
      questions:
      - Does the old /portal route still create a Stripe Customer Portal session?
      - Can I pass the CSRF token as a form field on the deprecated portal alias?
      instructions:
      - text: Open a customer portal session through the deprecated /portal alias.
      - text: Call the legacy portal route with form field csrf {csrf}.
        slots:
          csrf: requestBody.csrf
      method: generated
      generated: '2026-09-26'