# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Gitea Admin API
  version: 1.0.0
extends: openapi/gitea-admin-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: 32
- target: $.paths['/admin/actions/jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List all Actions jobs on the instance
      effect: read
      questions:
      - As a site admin, which Actions jobs are queued or running across the whole instance?
      - Can I filter instance-wide workflow jobs by status?
      instructions:
      - text: List every Actions job on the instance with status {status}.
        slots:
          status: query.status
      - text: Show the first {limit} workflow jobs across the whole server.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/actions/runners'].get
  update:
    x-apievangelist-phrasing:
      intent: List all global Actions runners
      effect: read
      questions:
      - Which instance-wide runners are registered on this Gitea server?
      - Can I see only the global runners that are disabled?
      instructions:
      - text: List all global Actions runners on the instance.
      - text: Show global runners where disabled is {disabled}.
        slots:
          disabled: query.disabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/actions/runners/registration-token'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a global runner registration token
      effect: write
      questions:
      - How do I get a token to register a runner that serves the entire instance?
      - Where does an admin get the global act runner registration token?
      instructions:
      - text: Generate a global runner registration token for the instance.
      - text: Give me the instance-wide token to register a shared Actions runner.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/actions/runners/{runner_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a global Actions runner
      effect: read
      questions:
      - What's the status of a specific instance-wide runner?
      - Can an admin look up one global runner by ID?
      instructions:
      - text: Show the global runner {runner_id}.
        slots:
          runner_id: path.runner_id
      - text: Check whether instance runner {runner_id} is online.
        slots:
          runner_id: path.runner_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/actions/runners/{runner_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a global Actions runner
      effect: destructive
      questions:
      - How do I unregister a shared runner from the whole instance?
      - Can an admin remove a global runner permanently?
      instructions:
      - text: Delete global runner {runner_id}.
        slots:
          runner_id: path.runner_id
      - text: Unregister instance-wide runner {runner_id}.
        slots:
          runner_id: path.runner_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/actions/runners/{runner_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Enable or disable a global runner
      effect: write
      questions:
      - Can I take a shared instance runner out of rotation without deleting it?
      - How does an admin re-enable a disabled global runner?
      instructions:
      - text: Set disabled to {disabled} on global runner {runner_id}.
        slots:
          disabled: requestBody.disabled
          runner_id: path.runner_id
      - text: Disable instance runner {runner_id} so it stops taking jobs.
        slots:
          runner_id: path.runner_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/actions/runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List all workflow runs on the instance
      effect: read
      questions:
      - Which workflow runs have happened across every repo on the server?
      - Can an admin filter instance-wide runs by actor, branch or commit?
      instructions:
      - text: List all workflow runs on the instance for branch {branch} with status {status}.
        slots:
          branch: query.branch
          status: query.status
      - text: Show instance-wide runs triggered by {event} from actor {actor}.
        slots:
          event: query.event
          actor: query.actor
      - text: Find every run on the server for commit {head_sha}.
        slots:
          head_sha: query.head_sha
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/cron'].get
  update:
    x-apievangelist-phrasing:
      intent: List scheduled cron tasks
      effect: read
      questions:
      - Which background cron tasks does this Gitea server run, and when did they last run?
      - Can I see the schedule of the instance's maintenance jobs?
      instructions:
      - text: List the server's cron tasks.
      - text: Show page {page} of scheduled cron tasks.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/cron/{task}'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a cron task immediately
      effect: write
      questions:
      - How do I trigger a maintenance cron job right now instead of waiting?
      - Can an admin manually kick off a specific cron task?
      instructions:
      - text: Run the cron task {task} now.
        slots:
          task: path.task
      - text: Trigger the {task} maintenance job immediately.
        slots:
          task: path.task
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/emails'].get
  update:
    x-apievangelist-phrasing:
      intent: List all user emails on the instance
      effect: read
      questions:
      - What email addresses are registered across all users on the server?
      - Can an admin export every user email page by page?
      instructions:
      - text: List every email address registered on the instance.
      - text: Show page {page} of all user emails.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/emails/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search user emails across the instance
      effect: read
      questions:
      - Which account owns a particular email address?
      - Can an admin search all emails by a keyword or domain?
      instructions:
      - text: Search all user emails for {q}.
        slots:
          q: query.q
      - text: Find which accounts have an email matching {q}.
        slots:
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/hooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List system-wide webhooks
      effect: read
      questions:
      - Which system and default webhooks are configured on this instance?
      - Can I list only the system hooks, or only the default ones?
      instructions:
      - text: List the instance's system webhooks.
      - text: Show system-level hooks of type {type}.
        slots:
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/hooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a system-wide webhook
      effect: write
      questions:
      - How does an admin add a webhook that applies to every repository?
      - Can a system hook be limited to particular events or branches?
      instructions:
      - text: Create a system {type} webhook with config {config}.
        slots:
          type: requestBody.type
          config: requestBody.config
      - text: Add an instance-wide {type} hook with config {config} for events {events}.
        slots:
          type: requestBody.type
          config: requestBody.config
          events: requestBody.events
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/hooks/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a system-wide webhook
      effect: read
      questions:
      - What URL and events does a given system hook use?
      - Can an admin look up one instance webhook by ID?
      instructions:
      - text: Show system webhook {id}.
        slots:
          id: path.id
      - text: Get the configuration of instance hook {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/hooks/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a system-wide webhook
      effect: destructive
      questions:
      - How do I remove a webhook that applies across the whole instance?
      - Can an admin delete a system hook by ID?
      instructions:
      - text: Delete system webhook {id}.
        slots:
          id: path.id
      - text: Remove instance-wide hook {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/hooks/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a system-wide webhook
      effect: write
      questions:
      - Can an admin deactivate a system hook without deleting it?
      - What's the way to change the events a system webhook fires on?
      instructions:
      - text: Set active to {active} on system webhook {id}.
        slots:
          active: requestBody.active
          id: path.id
      - text: Change instance hook {id} to fire on events {events}.
        slots:
          id: path.id
          events: requestBody.events
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/orgs'].get
  update:
    x-apievangelist-phrasing:
      intent: List all organizations on the instance
      effect: read
      questions:
      - Which organizations exist on this Gitea server?
      - Can an admin page through every org, including private ones?
      instructions:
      - text: List every organization on the instance.
      - text: Show page {page} of all organizations.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/unadopted'].get
  update:
    x-apievangelist-phrasing:
      intent: List unadopted repositories on disk
      effect: read
      questions:
      - Are there repository folders on disk that Gitea doesn't know about?
      - Can I filter unadopted repos by a name pattern?
      instructions:
      - text: List unadopted repositories on the server.
      - text: Find unadopted repositories matching {pattern}.
        slots:
          pattern: query.pattern
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/unadopted/{owner}/{repo}'].post
  update:
    x-apievangelist-phrasing:
      intent: Adopt unadopted files as a repository
      effect: write
      questions:
      - How do I turn a repository folder found on disk into a real Gitea repo?
      - Can an admin adopt orphaned repository files for a user?
      instructions:
      - text: Adopt the unadopted files at {owner}/{repo} as a repository.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Register the on-disk repo {repo} under {owner}.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/unadopted/{owner}/{repo}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete unadopted repository files
      effect: destructive
      questions:
      - How do I clean up orphaned repository files that were never adopted?
      - Can an admin delete an unadopted repo from disk?
      instructions:
      - text: Delete the unadopted files for {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Remove orphaned repo {repo} under {owner} from disk.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users'].get
  update:
    x-apievangelist-phrasing:
      intent: Search all users with admin filters
      effect: read
      questions:
      - Which accounts on the server are admins or have 2FA turned off?
      - Can I find users that are inactive or prohibited from logging in?
      - What users come from a particular authentication source?
      instructions:
      - text: Search all users for {q}.
        slots:
          q: query.q
      - text: List users where is_admin is {is_admin} and is_active is {is_active}.
        slots:
          is_admin: query.is_admin
          is_active: query.is_active
      - text: Find users from auth source {source_id} with login name {login_name}.
        slots:
          source_id: query.source_id
          login_name: query.login_name
      - text: List users with 2FA enabled set to {is_2fa_enabled}.
        slots:
          is_2fa_enabled: query.is_2fa_enabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user account
      effect: write
      questions:
      - How does an admin create a new user account directly?
      - Can I force a new user to change their password on first login?
      instructions:
      - text: Create user {username} with email {email}.
        slots:
          username: requestBody.username
          email: requestBody.email
      - text: Create user {username} ({email}) with password {password} and must change password {must_change_password}.
        slots:
          username: requestBody.username
          email: requestBody.email
          password: requestBody.password
          must_change_password: requestBody.must_change_password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users/{username}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user account
      effect: destructive
      questions:
      - How does an admin delete a user account?
      - Can I purge a user together with all their repositories and data?
      instructions:
      - text: Delete user {username}.
        slots:
          username: path.username
      - text: 'Delete user {username} and purge all their data: {purge}.'
        slots:
          username: path.username
          purge: query.purge
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users/{username}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a user account as admin
      effect: write
      questions:
      - How do I promote a user to site admin or prohibit their login?
      - Can an admin cap how many repos a user may create?
      instructions:
      - text: Set admin to {admin} for user {username} (login {login_name}, source {source_id}).
        slots:
          admin: requestBody.admin
          username: path.username
          login_name: requestBody.login_name
          source_id: requestBody.source_id
      - text: Prohibit login {prohibit_login} for {username} with login {login_name} and source {source_id}.
        slots:
          prohibit_login: requestBody.prohibit_login
          username: path.username
          login_name: requestBody.login_name
          source_id: requestBody.source_id
      - text: Limit {username} to {max_repo_creation} repos, login {login_name}, source {source_id}.
        slots:
          username: path.username
          max_repo_creation: requestBody.max_repo_creation
          login_name: requestBody.login_name
          source_id: requestBody.source_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users/{username}/badges'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's badges
      effect: read
      questions:
      - Which badges has a given user been awarded?
      - Can an admin see the badges on someone's profile?
      instructions:
      - text: List the badges for {username}.
        slots:
          username: path.username
      - text: Show which badges {username} holds.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users/{username}/badges'].post
  update:
    x-apievangelist-phrasing:
      intent: Award badges to a user
      effect: write
      questions:
      - How do I give a user a badge?
      - Can an admin award several badges at once?
      instructions:
      - text: Add badges {badge_slugs} to {username}.
        slots:
          badge_slugs: requestBody.badge_slugs
          username: path.username
      - text: Award {username} the badges {badge_slugs}.
        slots:
          badge_slugs: requestBody.badge_slugs
          username: path.username
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users/{username}/badges'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove badges from a user
      effect: destructive
      questions:
      - How do I take a badge away from a user?
      - Can an admin strip multiple badges from someone at once?
      instructions:
      - text: Remove badges {badge_slugs} from {username}.
        slots:
          badge_slugs: requestBody.badge_slugs
          username: path.username
      - text: Revoke {username}'s badges {badge_slugs}.
        slots:
          badge_slugs: requestBody.badge_slugs
          username: path.username
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users/{username}/keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an SSH key on behalf of a user
      effect: write
      questions:
      - Can an admin add an SSH key to someone else's account?
      - How do I install a read-only deploy-style key for a user as admin?
      instructions:
      - text: Add SSH key {key} titled {title} to user {username}.
        slots:
          key: requestBody.key
          title: requestBody.title
          username: path.username
      - text: On behalf of {username}, add key {key} named {title} with read only {read_only}.
        slots:
          key: requestBody.key
          title: requestBody.title
          username: path.username
          read_only: requestBody.read_only
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users/{username}/keys/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's SSH key as admin
      effect: destructive
      questions:
      - How does an admin remove a compromised SSH key from a user's account?
      - Can I delete another user's public key by ID?
      instructions:
      - text: Delete public key {id} from user {username}.
        slots:
          id: path.id
          username: path.username
      - text: Remove {username}'s SSH key {id}.
        slots:
          id: path.id
          username: path.username
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users/{username}/orgs'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization owned by a user
      effect: write
      questions:
      - Can an admin create an organization and make a specific user its owner?
      - How do I set a new org's visibility when creating it as admin?
      instructions:
      - text: Create organization {org_name} owned by {username}.
        slots:
          org_name: requestBody.username
          username: path.username
      - text: Create org {org_name} for {username} with visibility {visibility}.
        slots:
          org_name: requestBody.username
          username: path.username
          visibility: requestBody.visibility
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users/{username}/rename'].post
  update:
    x-apievangelist-phrasing:
      intent: Rename a user account
      effect: write
      questions:
      - How does an admin change someone's username?
      - Can I rename a user account through the API?
      instructions:
      - text: Rename user {username} to {new_username}.
        slots:
          username: path.username
          new_username: requestBody.new_username
      - text: Change the username of {username} to {new_username}.
        slots:
          username: path.username
          new_username: requestBody.new_username
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/users/{username}/repos'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a repository on behalf of a user
      effect: write
      questions:
      - Can an admin create a repository inside another user's account?
      - How do I provision a private repo for a user as admin?
      instructions:
      - text: Create repository {name} for user {username}.
        slots:
          name: requestBody.name
          username: path.username
      - text: On behalf of {username}, create private repo {name} with private set to {private}.
        slots:
          name: requestBody.name
          username: path.username
          private: requestBody.private
      method: generated
      generated: '2026-09-26'