Skip to content

Document the task-id query parameter - #32

Open
HouMinXi wants to merge 1 commit into
teemtee:mainfrom
HouMinXi:docs/task-id-parameter
Open

HouMinXi wants to merge 1 commit into
teemtee:mainfrom
HouMinXi:docs/task-id-parameter

Conversation

@HouMinXi

Copy link
Copy Markdown

The three endpoints that take a task identifier declare it as task-id
(Query(alias="task-id")), and tests/integration/test_api.py calls them the same
way. The README spelled it task_id, so a request built from the documentation does
not reach the handler:

$ curl -s -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1:8000/status?task_id=<id>'
422
{"detail":[{"type":"missing","loc":["query","task-id"],"msg":"Field required","input":null}]}

$ curl -s -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1:8000/status?task-id=<id>'
200

While there, two smaller gaps in the same section:

  • / accepts task-id as well, and returns the status of that task instead of
    creating a new one. It is not documented at all, although it is the path the
    /status/html redirect lands on.
  • /status/html answers with a status page while the task runs, and redirects with
    a 303 to /?task-id=<id> once it has succeeded. The README only mentioned the HTML
    formatting.

Verified against a local instance built from main (e4d55ec): the 422/200 pair
above, /?task-id=<id>&format=json returning the finished task, and /status/html
answering 200 with Task Status while pending and 303 to
http://localhost:8000/?task-id=<id> afterwards.

Docs only, no code or behaviour changes.

The status endpoints take the task identifier as ``task-id``: the
handlers declare it with ``Query(alias="task-id")`` and the integration
tests call them that way. The README spelled it ``task_id``, so a
request built from the docs got a 400 instead of a status.

Also mention the parameter on the ``/`` endpoint, which returns the
status of an existing task when it is set, and note that ``/status/html``
redirects once the task has succeeded.

Assisted-by: Hermes Agent
@HouMinXi

Copy link
Copy Markdown
Author

Hi @therazix @happz, gentle ping: this is a docs-only fix (README spelled the query parameter task_id, the API expects task-id). The workflows are waiting for approval since it's my first PR here. Could you approve the run and take a look when you have a moment? Thanks!

@psss psss added the documentation Improvements or additions to documentation label Oct 29, 2026
@psss psss added this to planning Oct 29, 2026
@github-project-automation github-project-automation Bot moved this to backlog in planning Oct 29, 2026
@psss psss moved this from backlog to review in planning Oct 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

Status: review

Development

Successfully merging this pull request may close these issues.

3 participants