list tasks.md
List Tasks
Returns persisted daily tasks with execution instructions. Includes per-status counts not narrowed by the status filter.
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:
get:
tags:
- Tasks
summary: List Tasks
description: >-
Returns persisted daily tasks with execution instructions. Includes
per-status counts not narrowed by the `status` filter.
operationId: v2_tasks_list
parameters:
- name: action_date
in: query
required: false
schema:
type: string
format: date
title: Action Date
description: Optional queue date in `YYYY-MM-DD` format.
- name: status
in: query
required: false
schema:
enum:
- active
- todo
- new
- in_progress
- completed
- done
- dismissed
- all
type: string
default: active
title: Status
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/V2ListTasksResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- LightsageApiKeyAuth: []
components:
schemas:
V2ListTasksResponse:
properties:
action_date:
type: string
title: Action Date
description: >-
The requested action date. It defaults to today in UTC even when
`data` spans every date.
status:
type: string
enum:
- active
- todo
- new
- in_progress
- completed
- done
- dismissed
- all
title: Status
description: The requested queue slice; this value is not itself a task status.
batch_number:
anyOf:
- type: integer
- type: 'null'
title: Batch Number
latest_batch_number:
type: integer
title: Latest Batch Number
default: 0
data:
items:
$ref: '#/components/schemas/V2PublicTask'
type: array
title: Data
count:
type: integer
title: Count
active_count:
type: integer
title: Active Count
default: 0
in_progress_count:
type: integer
title: In Progress Count
default: 0
completed_count:
type: integer
title: Completed Count
default: 0
done_count:
type: integer
title: Done Count
default: 0
dismissed_count:
type: integer
title: Dismissed Count
default: 0
history_count:
type: integer
title: History Count
default: 0
has_history:
type: boolean
title: Has History
default: false
can_fetch_next_batch:
type: boolean
title: Can Fetch Next Batch
default: false
generated_at:
anyOf:
- type: string
- type: 'null'
title: Generated At
type: object
required:
- action_date
- status
- count
title: V2ListTasksResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
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
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
This documentation is built and hosted on Mintlify, a developer documentation platform.