create task.md
Create Task
Adds a task to today's queue and returns it with its execution prompt. New tasks start as new.
OpenAPI
openapi: 3.1.0
info:
title: Lightsage Public API
description: Public API for Lightsage CLI and external integrations.
version: 1.0.0
servers:
- url: https://api.lightsage.com
description: Production
security: []
tags:
- name: Status
description: Check API availability and validate the calling API key.
- name: Visibility
description: >-
Measure visibility, citations, competitors, and prompt performance across
answer platforms.
- name: Prompts
description: Manage tracked prompts and topics, and inspect their stored runs.
- name: Opportunities
description: Review ranked opportunities computed from prompt visibility results.
- name: Tasks
description: Manage the persisted action queue and task lifecycle.
- name: Site Audits
description: Review website audit results and page-level findings.
- name: Agent Analytics
description: >-
See which coding agents, AI bots, and people visit your tracked sites,
which pages they read, which pages return errors, and where the visits
come from.
- name: Evals
description: Define eval tasks, judges, subjects, and saved configurations.
- name: Eval Templates
description: >-
Select reusable judges, targets, schedules, metadata, and runtime settings
with `POST /v2/eval-templates`, then copy only those settings into
prompt-specific evals with `POST /v2/evals/batch`. Templates never contain
prompts and remain independent from evals created from them.
- name: Eval Runs
description: Start eval runs and inspect their lifecycle state.
- name: Eval Results
description: Review completed eval outcomes and diagnostic details.
- name: Agent Preference
description: >-
Compare your company head-to-head with a tracked competitor. Create a
comparison with `POST /v2/agent-preference/evals`, run it with `POST
/v2/eval-runs`, then read which company agents recommended.
- name: Agents
description: List runnable coding-agent harness and model combinations.
- name: Repositories
description: Manage reusable Git repository workspaces.
- name: Environments
description: List reusable runtime environments without exposing secret values.
- name: MCP Servers
description: List reusable MCP server integrations without exposing credentials.
- name: CLIs
description: List reusable command-line interfaces without exposing setup commands.
- name: Skills
description: List reusable skills available to workflows and evals.
paths:
/v2/tasks:
post:
tags:
- Tasks
summary: Create Task
description: >-
Adds a task to today's queue and returns it with its execution prompt.
New tasks start as `new`.
operationId: v2_tasks_create
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTaskRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/V2PublicTask'
'400':
description: The assignee is not a member of your organization.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
required:
- detail
example:
detail: Assignee must be a member of your organization
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- LightsageApiKeyAuth: []
components:
schemas:
CreateTaskRequest:
properties:
title:
type: string
maxLength: 200
minLength: 1
title: Title
description:
type: string
maxLength: 10000
title: Description
description: A Markdown description of what to do and why.
task_type:
type: string
enum:
- Create
- Refresh
- Win back
- Outreach
- Community
- Docs
- Redirect
title: Task Type
default: Create
effort:
type: string
enum:
- Low
- Medium
- High
title: Effort
default: Medium
priority:
type: string
enum:
- urgent
- high
- medium
- low
title: Priority
default: medium
action_type:
type: string
enum:
- agent_discovery
- agent_usability
title: Action Type
default: agent_discovery
assignee_user_id:
type: string
title: Assignee User Id
description: >-
A member of your organization to assign the task to. They are
emailed unless they have turned off task notifications.
additionalProperties: false
type: object
required:
- title
title: CreateTaskRequest
V2PublicTask:
properties:
id:
type: string
title: Id
action_date:
type: string
title: Action Date
batch_number:
type: integer
title: Batch Number
rank:
type: integer
title: Rank
description: Sort order within the batch, ascending; values need not start at 1.
source_key:
type: string
title: Source Key
description: >-
A finding key namespaced by source, such as
`api_perf:https://example.com/docs/cli`.
task_type:
type: string
title: Task Type
description: >-
A free-form label such as `Redirect` or `Docs`; this field is not an
enum.
title:
type: string
title: Title
why:
type: string
title: Why
next_action:
type: string
title: Next Action
description:
anyOf:
- type: string
- type: 'null'
title: Description
execution_prompt:
type: string
title: Execution Prompt
content:
anyOf:
- type: string
- type: 'null'
title: Content
description: >-
The task's Markdown write-up covering what went wrong, how to fix
it, the impact, and the evidence. Null until the write-up is
generated; see `content_status`.
target_url:
anyOf:
- type: string
- type: 'null'
title: Target Url
description: The page the fix should be made on, when the task targets one.
content_status:
type: string
enum:
- none
- writing
- ready
- failed
title: Content Status
description: Progress of the Markdown write-up in `content`.
default: none
content_written_at:
anyOf:
- type: string
- type: 'null'
title: Content Written At
description: When the write-up in `content` was last generated.
reasoning:
anyOf:
- type: string
- type: 'null'
title: Reasoning
evidence:
additionalProperties: true
type: object
title: Evidence
description: >-
Supporting evidence with keys such as `expected_lift`,
`failure_traces`, `source_prompts`, and `source_urls`.
score:
anyOf:
- type: number
- type: 'null'
title: Score
description: Planner impact score; manually created tasks may be unscored.
effort:
type: string
title: Effort
description: >-
A free-form effort estimate such as `Low` or `Medium`; this field is
not an enum.
priority:
anyOf:
- type: string
- type: 'null'
title: Priority
status:
type: string
title: Status
description: >-
The workflow status. New tasks start as `new`. A task is `in_review`
while its content waits to go live, as an open pull request or a CMS
draft; it is listed with `in_progress` tasks. `added_to_sheet` and
`snoozed` tasks are listed only when `status=all`.
assignee_user_id:
anyOf:
- type: string
- type: 'null'
title: Assignee User Id
function_area:
anyOf:
- type: string
- type: 'null'
title: Function Area
action_type:
anyOf:
- type: string
- type: 'null'
title: Action Type
source:
anyOf:
- type: string
- type: 'null'
title: Source
source_type:
anyOf:
- type: string
- type: 'null'
title: Source Type
description: >-
A free-form source type such as `api_performance`; manually created
tasks may not have a source.
source_refs:
additionalProperties: true
type: object
title: Source Refs
description: Source references needed to understand or execute the task.
metadata:
additionalProperties: true
type: object
title: Metadata
description: >-
Additional task metadata, including `source_key`, `impact_score`,
`disposition`, `target_urls`, `edit_locations` (where on the target
page each change goes: `url`, `anchor` heading, `placement` of `in`,
`after`, or `before`, and `change`), `evidence_summary`,
`source_start_date`, and `source_end_date`.
created_at:
anyOf:
- type: string
- type: 'null'
title: Created At
updated_at:
anyOf:
- type: string
- type: 'null'
title: Updated At
additionalProperties: true
type: object
required:
- id
- action_date
- batch_number
- rank
- source_key
- task_type
- title
- why
- next_action
- execution_prompt
- effort
- status
title: V2PublicTask
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
LightsageApiKeyAuth:
type: apiKey
in: header
name: X-Lightsage-Api-Key