docs(api): applications endpoint docstrings + concept page by mmabrouk · Pull Request #4232 · Agenta-AI/agenta

mmabrouk · 2026-04-28T10:10:21Z

Summary

Adds docs/docs/reference/api-guide/05-applications.mdx — concept page (~600 words) covering what an application is, the versioning model, invocation, deployment to environments, simple vs structured surfaces, catalog/templates, and lifecycle.
Adds Python docstrings on every handler in applications/router.py plus Field(description=...) on every request/response field in applications/models.py.
~35 endpoints documented across the structured and simple surfaces.
Cross-links to companion PRs: docs(docs): add versioning concept page #4175 (versioning), docs(api): evaluators endpoint docstrings + concept page #4178 (evaluators), docs(api): folders endpoint docstrings + concept page #4179 (folders), and the rest of the docs overhaul series.

Process notes

Pre-commit / gitleaks were not available in the sandbox where the agent worked. Commit was made with --no-verify. No secrets touched (docs + docstrings only). Hooks should be re-run locally before merge.
Agent died on API rate limit before pushing; this PR was opened from the salvaged worktree.

Test plan

Endpoints exercised against eu.cloud.agenta.ai
Examples obfuscated; shapes match real responses
Reviewer: verify docstring wording on any endpoint with uncertainty
Reviewer: re-run pre-commit hooks locally before merge

- Add `docs/docs/reference/api-guide/05-applications.mdx` covering what an application is, versioning, invocation, deployment, simple vs structured endpoints, catalog, lifecycle, and an end-to-end worked example. - Add docstrings to all 35 Applications FastAPI handlers (29 structured + 6 simple), explaining what each endpoint does and when to pick it over a similar one. - Add `Field(description=...)` to every field on the applications request and response models, including the catalog and simple-application models. - Every endpoint was exercised against `eu.cloud.agenta.ai` before its docstring was written. - Hooks skipped in sandbox; will be run locally before merge. No secrets in this PR (docs + docstrings only).

linear · 2026-04-28T10:10:24Z

AGE-3734 Tracing: query↔ingest schema asymmetry on ag.metrics.duration.cumulative

vercel · 2026-04-28T10:10:26Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Error		May 11, 2026 7:07pm

…plications-endpoints Resolve conflict in api/oss/src/apis/fastapi/applications/models.py: response envelopes now extend the new Support base class (from oss.src.utils.exceptions) while keeping the documentation docstrings and Field(description=...) introduced on this branch. No conflicts elsewhere. Router and concept page pick up cleanly from main.

`POST /applications/variants/fork` now raises `400 Bad Request` when the fork target is invalid (introduced in 77cb317 "workflow-related fork issues"). Add a short note to the handler docstring so the generated OpenAPI reflects the failure mode. No behavioral change.

coderabbitai · 2026-05-11T18:33:01Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c64a95b8-1181-42fd-8f40-fa3e854da26a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/age-3734-applications-endpoints

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

mmabrouk · 2026-05-11T18:33:11Z

Reconciliation pass (wave 1)

Rebased onto the umbrella branch and ran the OpenAPI drift sweep. Live-API verification and inline review feedback are deferred to a later wave.

Umbrella merged in

a451ea3d9 — merge of docs/age-3734-versioning-guide into docs/age-3734-api-reference-epic (versioning concept page now landed in the umbrella).

Conflicts resolved

Single conflict file:

api/oss/src/apis/fastapi/applications/models.py — every response envelope (ApplicationResponse, ApplicationsResponse, variant + revision + simple + catalog responses) needed to extend the new Support base class introduced upstream by 9e168825a [chore] Add support ID/timestamp to suppressed exceptions. Resolution: keep the docstrings and Field(description=...) annotations from this branch, change the parent class from BaseModel to Support. No semantic change.

Other touched files in the merge applied cleanly (no overlap with the docs work).

OpenAPI drift sweep

Compared docs/docs/reference/openapi.json (latest umbrella spec) against the routes registered in api/oss/src/apis/fastapi/applications/router.py:

Endpoint count: 35 operations in spec, 35 routes in router. Operation IDs match 1:1.
No new endpoints, no removed endpoints, no renames.
Field changes: the only upstream change to application models/router since the branch was cut is Support (support_id, support_ts) on suppressed-exception payloads — a cross-cutting concern, not domain-specific, so it's not documented in the applications page or in per-field descriptions.
Behavior change worth noting: POST /applications/variants/fork now raises HTTPException(400) on VariantForkError (from 77cb317d9 [fix] workflow-related fork issues). Added a one-line note to the fork_application_variant docstring.

`ag_config` check

Per the AGE-3756 / 91d3b4a8c27f migration note, the documented payload shape on this branch is already data.parameters.{...}. Grepped both docs/docs/reference/api-guide/05-applications.mdx and api/oss/src/apis/fastapi/applications/ for ag_config — no matches.

Pushed

6532e6a22 on docs/age-3734-applications-endpoints.

Out of scope (deferred to verification wave)

Re-running each endpoint against eu.cloud.agenta.ai.
Applying any review comments (none yet on this PR).
Promoting draft → ready.

mmabrouk · 2026-05-11T18:58:29Z

+sidebar_position: 5
+---
+
+An **application** is a versioned resource that serves inference. It wraps a prompt template, model parameters, and JSON schemas for its inputs, outputs, and parameters. Every deployment in Agenta — a chatbot, a classifier, a structured-extraction endpoint — is an application.


I would make it simple and then complex. An application can be a chat / completion. An application is versioned and wraps the parameters of the propmmt, that si...

something like this.

Also don't say every deployment in agenta is.. what does deployment mean even

I would also say that an application can be used in that it is invoked if its runnable or its configuratino used

I would also say custom workflows (and link) are application

mmabrouk · 2026-05-11T19:00:54Z

+
+## Catalog
+
+Applications are created from a **template**. Templates describe the handler URI and the JSON schemas an application of that type uses. Built-in templates include `completion`, `chat`, `hook` (custom HTTP), and `code` (custom code).


it's unclear what URI, json schema ..

I would before explain that application can be runned, and that the uri and json schema determine what are run

I would say also before somewhere taht agenta come with two application chat and completion

I would like to workflows also for core concept

…' into docs/age-3734-applications-endpoints

Rewrites the intro to lead with the customer-facing model (chat / completion endpoint), introduces the built-in application types up front, and links custom workflows as another kind of application. Splits the `data` payload section so `uri` + `schemas` are explained as drivers of execution before the catalog is referenced. Removes remaining em dashes.

github-actions · 2026-05-11T19:21:07Z

Railway Preview Environment


Preview URL	https://gateway-production-70ae.up.railway.app/w
Image tag	`pr-4232-f4ff67f`
Status	Failed
Railway logs	Open logs
Logs	View workflow run
Updated at 2026-05-11T19:21:06.531Z

This was referenced Apr 28, 2026

docs(api): testsets endpoint docstrings + concept page #4233

Draft

docs(api): workflows endpoint docstrings + concept page #4234

Draft

docs(api): tracing endpoint docstrings + concept page #4235

Draft

mmabrouk mentioned this pull request May 11, 2026

docs(api): API reference docs umbrella (AGE-3734) #4314

Draft

4 tasks

mmabrouk changed the base branch from main to docs/age-3734-api-reference-epic May 11, 2026 18:08

mmabrouk added 2 commits May 11, 2026 20:30

vercel Bot had a problem deploying to Preview May 11, 2026 18:34 Failure

mmabrouk commented May 11, 2026

View reviewed changes

mmabrouk added 2 commits May 11, 2026 21:04

Merge remote-tracking branch 'origin/docs/age-3734-api-reference-epic…

99f67df

…' into docs/age-3734-applications-endpoints

mmabrouk marked this pull request as ready for review May 11, 2026 19:06

dosubot Bot added the size:XXL This PR changes 1000+ lines, ignoring generated files. label May 11, 2026

mmabrouk merged commit 1375626 into docs/age-3734-api-reference-epic May 11, 2026
14 of 15 checks passed

dosubot Bot added the documentation Improvements or additions to documentation label May 11, 2026

vercel Bot had a problem deploying to Preview May 11, 2026 19:07 Failure

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(api): applications endpoint docstrings + concept page#4232

docs(api): applications endpoint docstrings + concept page#4232
mmabrouk merged 5 commits into
docs/age-3734-api-reference-epicfrom
docs/age-3734-applications-endpoints

mmabrouk commented Apr 28, 2026

Uh oh!

linear Bot commented Apr 28, 2026

Uh oh!

vercel Bot commented Apr 28, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 11, 2026

Review skipped

Uh oh!

mmabrouk commented May 11, 2026

Uh oh!

mmabrouk May 11, 2026

Uh oh!

mmabrouk May 11, 2026

Uh oh!

mmabrouk May 11, 2026

Uh oh!

mmabrouk May 11, 2026

Uh oh!

Uh oh!

github-actions Bot commented May 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		## Catalog

		Applications are created from a template. Templates describe the handler URI and the JSON schemas an application of that type uses. Built-in templates include `completion`, `chat`, `hook` (custom HTTP), and `code` (custom code).

Conversation

mmabrouk commented Apr 28, 2026

Summary

Process notes

Related

Test plan

Uh oh!

linear Bot commented Apr 28, 2026

Uh oh!

vercel Bot commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented May 11, 2026

Review skipped

Uh oh!

mmabrouk commented May 11, 2026

Reconciliation pass (wave 1)

Umbrella merged in

Conflicts resolved

OpenAPI drift sweep

ag_config check

Pushed

Out of scope (deferred to verification wave)

Uh oh!

mmabrouk May 11, 2026

Choose a reason for hiding this comment

Uh oh!

mmabrouk May 11, 2026

Choose a reason for hiding this comment

Uh oh!

mmabrouk May 11, 2026

Choose a reason for hiding this comment

Uh oh!

mmabrouk May 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented May 11, 2026

Railway Preview Environment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel Bot commented Apr 28, 2026 •

edited

Loading

`ag_config` check