API Evangelist conversational phrasing for External Projects API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for External Projects API
  version: 1.0.0
extends: openapi/profound-projects-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: 15
- target: $.paths['/v1/projects'].get
  update:
    x-apievangelist-phrasing:
      intent: List content projects in a category
      effect: read
      questions:
      - What content projects exist for one of my categories?
      - Can I list only archived projects?
      instructions:
      - text: List the projects in category {category_id}.
        slots:
          category_id: query.category_id
      - text: Show {limit} projects with status {status} in category {category_id}, offset {offset}.
        slots:
          limit: query.limit
          status: query.status
          category_id: query.category_id
          offset: query.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a content project
      effect: write
      questions:
      - How do I start a new content project for a category?
      - Can I give a new project a focus, topics and attachments when creating it?
      instructions:
      - text: Create a project in category {category_id} titled {title}.
        slots:
          category_id: requestBody.category_id
          title: requestBody.title
      - text: Start project {project_name} in category {category_id} focused on {focus} covering topics {topics}.
        slots:
          project_name: requestBody.project_name
          category_id: requestBody.category_id
          focus: requestBody.focus
          topics: requestBody.topics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/generations'].get
  update:
    x-apievangelist-phrasing:
      intent: List project generation runs
      effect: read
      questions:
      - Which project generation jobs have run in my category?
      - Can I filter project generation runs by their status?
      instructions:
      - text: List project generation runs for category {category_id}.
        slots:
          category_id: query.category_id
      - text: Show {limit} generation runs with status {status} in category {category_id}.
        slots:
          limit: query.limit
          status: query.status
          category_id: query.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/generations/{run_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a project generation run
      effect: read
      questions:
      - Is my project generation job finished yet?
      - Can I check progress on one specific generation run?
      instructions:
      - text: Check generation run {run_id} in category {category_id}.
        slots:
          run_id: path.run_id
          category_id: query.category_id
      - text: Tell me whether project generation {run_id} for category {category_id} has completed.
        slots:
          run_id: path.run_id
          category_id: query.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{project_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a content project
      effect: read
      questions:
      - Can I view the full details of one content project?
      - Where do I see a project's title, focus and topics?
      instructions:
      - text: Show project {project_id} in category {category_id}.
        slots:
          project_id: path.project_id
          category_id: query.category_id
      - text: Get the details of content project {project_id} under category {category_id}.
        slots:
          project_id: path.project_id
          category_id: query.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{project_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a content project
      effect: destructive
      questions:
      - How do I permanently remove a content project?
      - Is deleting a project different from archiving it?
      instructions:
      - text: Delete project {project_id} from category {category_id}.
        slots:
          project_id: path.project_id
          category_id: query.category_id
      - text: Permanently remove content project {project_id} in category {category_id}.
        slots:
          project_id: path.project_id
          category_id: query.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{project_id}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a content project's status
      effect: read
      questions:
      - What state is my content project in right now?
      - Can I check just the status of a project without its full details?
      instructions:
      - text: Get the status of project {project_id} in category {category_id}.
        slots:
          project_id: path.project_id
          category_id: query.category_id
      - text: Is content project {project_id} (category {category_id}) ready? Check its status.
        slots:
          project_id: path.project_id
          category_id: query.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{project_id}/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive a content project
      effect: write
      questions:
      - Can I put a finished project away without deleting it?
      - How do I hide a project from my active list?
      instructions:
      - text: Archive project {project_id} in category {category_id}.
        slots:
          project_id: path.project_id
          category_id: query.category_id
      - text: Move content project {project_id} of category {category_id} into the archive.
        slots:
          project_id: path.project_id
          category_id: query.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{project_id}/unarchive'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore an archived content project
      effect: write
      questions:
      - Can I bring an archived project back to active?
      - How do I restore a project I archived by mistake?
      instructions:
      - text: Unarchive project {project_id} in category {category_id}.
        slots:
          project_id: path.project_id
          category_id: query.category_id
      - text: Restore archived content project {project_id} for category {category_id}.
        slots:
          project_id: path.project_id
          category_id: query.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{project_id}/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List the tasks in a project
      effect: read
      questions:
      - What tasks are on a content project's to-do list?
      - Can I see every task belonging to one project?
      instructions:
      - text: List the tasks in project {project_id} for category {category_id}.
        slots:
          project_id: path.project_id
          category_id: query.category_id
      - text: Show all to-dos on content project {project_id} (category {category_id}).
        slots:
          project_id: path.project_id
          category_id: query.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{project_id}/tasks'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a task to a project
      effect: write
      questions:
      - How do I add a task to a content project?
      - Can a new task carry a brief, an impact level and a reference link?
      instructions:
      - text: Add task {title} to project {project_id} in category {category_id}.
        slots:
          title: requestBody.title
          project_id: path.project_id
          category_id: query.category_id
      - text: Create a {type} task {title} with impact {impact} and reference {reference_url} on project {project_id}, category {category_id}.
        slots:
          type: requestBody.type
          title: requestBody.title
          impact: requestBody.impact
          reference_url: requestBody.reference_url
          project_id: path.project_id
          category_id: query.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{project_id}/tasks/{task_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one project task
      effect: read
      questions:
      - Can I view the full brief for one task in a project?
      - Where do I see a single task's impact and reference link?
      instructions:
      - text: Show task {task_id} in project {project_id}, category {category_id}.
        slots:
          task_id: path.task_id
          project_id: path.project_id
          category_id: query.category_id
      - text: Get the details of to-do {task_id} on project {project_id} for category {category_id}.
        slots:
          task_id: path.task_id
          project_id: path.project_id
          category_id: query.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{project_id}/tasks/{task_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a project task
      effect: destructive
      questions:
      - How do I remove a task from a project?
      - Can I delete a to-do that's no longer relevant?
      instructions:
      - text: Delete task {task_id} from project {project_id} in category {category_id}.
        slots:
          task_id: path.task_id
          project_id: path.project_id
          category_id: query.category_id
      - text: Remove to-do {task_id} on project {project_id}, category {category_id}.
        slots:
          task_id: path.task_id
          project_id: path.project_id
          category_id: query.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{project_id}/tasks/{task_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a project task's details
      effect: write
      questions:
      - Can I change a task's title, brief or impact after creating it?
      - How do I update the reference link on an existing task?
      instructions:
      - text: Rename task {task_id} on project {project_id} (category {category_id}) to {title}.
        slots:
          task_id: path.task_id
          project_id: path.project_id
          category_id: query.category_id
          title: requestBody.title
      - text: Change the brief of task {task_id} in project {project_id}, category {category_id}, to {brief}.
        slots:
          task_id: path.task_id
          project_id: path.project_id
          category_id: query.category_id
          brief: requestBody.brief
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/projects/{project_id}/tasks/{task_id}/status'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a project task's status
      effect: write
      questions:
      - How do I mark a project task as done?
      - Can I leave a note when moving a task to a new status?
      instructions:
      - text: Set task {task_id} on project {project_id} (category {category_id}) to status {status}.
        slots:
          task_id: path.task_id
          project_id: path.project_id
          category_id: query.category_id
          status: requestBody.status
      - text: Move task {task_id} in project {project_id}, category {category_id}, to {status} with note {note}.
        slots:
          task_id: path.task_id
          project_id: path.project_id
          category_id: query.category_id
          status: requestBody.status
          note: requestBody.note
      method: generated
      generated: '2026-10-01'