chore(API docs): link to related docs pages

docs/v3/api-ref/rest-api/server/schema.json

@@ -58,7 +58,7 @@
                     "Flows"
                 ],
                 "summary": "Create Flow",
-                "description": "Gracefully creates a new flow from the provided schema. If a flow with the\nsame name already exists, the existing flow is returned.",
+                "description": "Gracefully creates a new flow from the provided schema. If a flow with the\nsame name already exists, the existing flow is returned.\n\nFor more information, see https://docs.prefect.io/v3/develop/write-flows.",
                 "operationId": "create_flow_flows__post",
                 "parameters": [
                     {
@@ -483,7 +483,7 @@
                     "Flow Runs"
                 ],
                 "summary": "Create Flow Run",
-                "description": "Create a flow run. If a flow run with the same flow_id and\nidempotency key already exists, the existing flow run will be returned.\n\nIf no state is provided, the flow run will be created in a PENDING state.",
+                "description": "Create a flow run. If a flow run with the same flow_id and\nidempotency key already exists, the existing flow run will be returned.\n\nIf no state is provided, the flow run will be created in a PENDING state.\n\nFor more information, see https://docs.prefect.io/v3/develop/write-flows.",
                 "operationId": "create_flow_run_flow_runs__post",
                 "parameters": [
                     {
@@ -1593,7 +1593,7 @@
                     "Task Runs"
                 ],
                 "summary": "Create Task Run",
-                "description": "Create a task run. If a task run with the same flow_run_id,\ntask_key, and dynamic_key already exists, the existing task\nrun will be returned.\n\nIf no state is provided, the task run will be created in a PENDING state.",
+                "description": "Create a task run. If a task run with the same flow_run_id,\ntask_key, and dynamic_key already exists, the existing task\nrun will be returned.\n\nIf no state is provided, the task run will be created in a PENDING state.\n\nFor more information, see https://docs.prefect.io/v3/develop/write-tasks.",
                 "operationId": "create_task_run_task_runs__post",
                 "parameters": [
                     {
@@ -2034,7 +2034,7 @@
                     "Flow Run States"
                 ],
                 "summary": "Read Flow Run State",
-                "description": "Get a flow run state by id.",
+                "description": "Get a flow run state by id.\n\nFor more information, see https://docs.prefect.io/v3/develop/write-flows#final-state-determination.",
                 "operationId": "read_flow_run_state_flow_run_states__id__get",
                 "parameters": [
                     {
@@ -2146,7 +2146,7 @@
                     "Task Run States"
                 ],
                 "summary": "Read Task Run State",
-                "description": "Get a task run state by id.",
+                "description": "Get a task run state by id.\n\nFor more information, see https://docs.prefect.io/v3/develop/write-tasks.",
                 "operationId": "read_task_run_state_task_run_states__id__get",
                 "parameters": [
                     {
@@ -2258,7 +2258,7 @@
                     "Flow Run Notification Policies"
                 ],
                 "summary": "Create Flow Run Notification Policy",
-                "description": "Creates a new flow run notification policy.",
+                "description": "Creates a new flow run notification policy.\n\nFor more information, see https://docs.prefect.io/v3/automate/events/automations-triggers#sending-notifications-with-automations.",
                 "operationId": "create_flow_run_notification_policy_flow_run_notification_policies__post",
                 "parameters": [
                     {
@@ -2524,7 +2524,7 @@
                     "Deployments"
                 ],
                 "summary": "Create Deployment",
-                "description": "Gracefully creates a new deployment from the provided schema. If a deployment with\nthe same name and flow_id already exists, the deployment is updated.\n\nIf the deployment has an active schedule, flow runs will be scheduled.\nWhen upserting, any scheduled runs from the existing deployment will be deleted.",
+                "description": "Gracefully creates a new deployment from the provided schema. If a deployment with\nthe same name and flow_id already exists, the deployment is updated.\n\nIf the deployment has an active schedule, flow runs will be scheduled.\nWhen upserting, any scheduled runs from the existing deployment will be deleted.\n\nFor more information, see https://docs.prefect.io/v3/deploy.",
                 "operationId": "create_deployment_deployments__post",
                 "parameters": [
                     {
@@ -3775,7 +3775,7 @@
                     "Logs"
                 ],
                 "summary": "Create Logs",
-                "description": "Create new logs from the provided schema.",
+                "description": "Create new logs from the provided schema.\n\nFor more information, see https://docs.prefect.io/v3/develop/logging.",
                 "operationId": "create_logs_logs__post",
                 "parameters": [
                     {
@@ -3886,6 +3886,7 @@
                     "Concurrency Limits"
                 ],
                 "summary": "Create Concurrency Limit",
+                "description": "Create a task run concurrency limit.\n\nFor more information, see https://docs.prefect.io/v3/develop/task-run-limits.",
                 "operationId": "create_concurrency_limit_concurrency_limits__post",
                 "parameters": [
                     {
@@ -4368,6 +4369,7 @@
                     "Concurrency Limits V2"
                 ],
                 "summary": "Create Concurrency Limit V2",
+                "description": "Create a task run concurrency limit.\n\nFor more information, see https://docs.prefect.io/v3/develop/global-concurrency-limits.",
                 "operationId": "create_concurrency_limit_v2_v2_concurrency_limits__post",
                 "parameters": [
                     {
@@ -4762,7 +4764,7 @@
                     "Block types"
                 ],
                 "summary": "Create Block Type",
-                "description": "Create a new block type",
+                "description": "Create a new block type.\n\nFor more information, see https://docs.prefect.io/v3/develop/blocks.",
                 "operationId": "create_block_type_block_types__post",
                 "parameters": [
                     {
@@ -5270,7 +5272,7 @@
                     "Block documents"
                 ],
                 "summary": "Create Block Document",
-                "description": "Create a new block document.",
+                "description": "Create a new block document.\n\nFor more information, see https://docs.prefect.io/v3/develop/blocks.",
                 "operationId": "create_block_document_block_documents__post",
                 "parameters": [
                     {
@@ -5598,7 +5600,7 @@
                     "Work Pools"
                 ],
                 "summary": "Create Work Pool",
-                "description": "Creates a new work pool. If a work pool with the same\nname already exists, an error will be raised.",
+                "description": "Creates a new work pool. If a work pool with the same\nname already exists, an error will be raised.\n\nFor more information, see https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools.",
                 "operationId": "create_work_pool_work_pools__post",
                 "parameters": [
                     {
@@ -5981,7 +5983,7 @@
                     "Work Pools"
                 ],
                 "summary": "Create Work Queue",
-                "description": "Creates a new work pool queue. If a work pool queue with the same\nname already exists, an error will be raised.",
+                "description": "Creates a new work pool queue. If a work pool queue with the same\nname already exists, an error will be raised.\n\nFor more information, see https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools#work-queues.",
                 "operationId": "create_work_queue_work_pools__work_pool_name__queues_post",
                 "parameters": [
                     {
@@ -6480,7 +6482,7 @@
                     "Task Workers"
                 ],
                 "summary": "Read Task Workers",
-                "description": "Read active task workers. Optionally filter by task keys.",
+                "description": "Read active task workers. Optionally filter by task keys.\n\nFor more information, see https://docs.prefect.io/v3/develop/deferred-tasks.",
                 "operationId": "read_task_workers_task_workers_filter_post",
                 "parameters": [
                     {
@@ -6536,7 +6538,7 @@
                     "Work Queues"
                 ],
                 "summary": "Create Work Queue",
-                "description": "Creates a new work queue.\n\nIf a work queue with the same name already exists, an error\nwill be raised.",
+                "description": "Creates a new work queue.\n\nIf a work queue with the same name already exists, an error\nwill be raised.\n\nFor more information, see https://docs.prefect.io/v3/deploy/infrastructure-concepts/work-pools#work-queues.",
                 "operationId": "create_work_queue_work_queues__post",
                 "parameters": [
                     {
@@ -6998,6 +7000,7 @@
                     "Artifacts"
                 ],
                 "summary": "Create Artifact",
+                "description": "Create an artifact.\n\nFor more information, see https://docs.prefect.io/v3/develop/artifacts.",
                 "operationId": "create_artifact_artifacts__post",
                 "parameters": [
                     {
@@ -7479,6 +7482,7 @@
                     "Block schemas"
                 ],
                 "summary": "Create Block Schema",
+                "description": "Create a block schema.\n\nFor more information, see https://docs.prefect.io/v3/develop/blocks.",
                 "operationId": "create_block_schema_block_schemas__post",
                 "parameters": [
                     {
@@ -7759,6 +7763,7 @@
                     "Block capabilities"
                 ],
                 "summary": "Read Available Block Capabilities",
+                "description": "Get available block capabilities.\n\nFor more information, see https://docs.prefect.io/v3/develop/blocks.",
                 "operationId": "read_available_block_capabilities_block_capabilities__get",
                 "parameters": [
                     {
@@ -7858,6 +7863,7 @@
                     "Variables"
                 ],
                 "summary": "Create Variable",
+                "description": "Create a variable.\n\nFor more information, see https://docs.prefect.io/v3/develop/variables.",
                 "operationId": "create_variable_variables__post",
                 "parameters": [
                     {
@@ -8361,7 +8367,7 @@
                     "Events"
                 ],
                 "summary": "Create Events",
-                "description": "Record a batch of Events",
+                "description": "Record a batch of Events.\n\nFor more information, see https://docs.prefect.io/v3/automate/events/events.",
                 "operationId": "create_events_events_post",
                 "parameters": [
                     {
@@ -8580,6 +8586,7 @@
                     "Automations"
                 ],
                 "summary": "Create Automation",
+                "description": "Create an automation.\n\nFor more information, see https://docs.prefect.io/v3/automate.",
                 "operationId": "create_automation_automations__post",
                 "parameters": [
                     {

src/prefect/server/api/artifacts.py

@@ -26,6 +26,11 @@ async def create_artifact(
     response: Response,
     db: PrefectDBInterface = Depends(provide_database_interface),
 ) -> core.Artifact:
+    """
+    Create an artifact.
+
+    For more information, see https://docs.prefect.io/v3/develop/artifacts.
+    """
     artifact = core.Artifact(**artifact.model_dump())
 
     right_now = now("UTC")

src/prefect/server/api/automations.py

@@ -39,6 +39,11 @@ async def create_automation(
     automation: AutomationCreate,
     db: PrefectDBInterface = Depends(provide_database_interface),
 ) -> Automation:
+    """
+    Create an automation.
+
+    For more information, see https://docs.prefect.io/v3/automate.
+    """
     # reset any client-provided IDs on the provided triggers
     automation.trigger.reset_ids()
 

src/prefect/server/api/block_capabilities.py

@@ -19,6 +19,11 @@
 async def read_available_block_capabilities(
     db: PrefectDBInterface = Depends(provide_database_interface),
 ) -> List[str]:
+    """
+    Get available block capabilities.
+
+    For more information, see https://docs.prefect.io/v3/develop/blocks.
+    """
     async with db.session_context() as session:
         return await models.block_schemas.read_available_block_capabilities(
             session=session

src/prefect/server/api/block_documents.py

@@ -24,6 +24,8 @@ async def create_block_document(
 ) -> schemas.core.BlockDocument:
     """
     Create a new block document.
+
+    For more information, see https://docs.prefect.io/v3/develop/blocks.
     """
     async with db.session_context(begin_transaction=True) as session:
         if block_document.name is not None:

src/prefect/server/api/block_schemas.py

@@ -30,6 +30,11 @@ async def create_block_schema(
     response: Response,
     db: PrefectDBInterface = Depends(provide_database_interface),
 ) -> schemas.core.BlockSchema:
+    """
+    Create a block schema.
+
+    For more information, see https://docs.prefect.io/v3/develop/blocks.
+    """
     from prefect.blocks.core import Block
 
     async with db.session_context(begin_transaction=True) as session:

src/prefect/server/api/block_types.py

@@ -19,7 +19,9 @@ async def create_block_type(
     db: PrefectDBInterface = Depends(provide_database_interface),
 ) -> schemas.core.BlockType:
     """
-    Create a new block type
+    Create a new block type.
+
+    For more information, see https://docs.prefect.io/v3/develop/blocks.
     """
     # API-created blocks cannot start with the word "Prefect"
     # as it is reserved for system use

src/prefect/server/api/concurrency_limits.py

@@ -28,6 +28,11 @@ async def create_concurrency_limit(
     response: Response,
     db: PrefectDBInterface = Depends(provide_database_interface),
 ) -> schemas.core.ConcurrencyLimit:
+    """
+    Create a task run concurrency limit.
+
+    For more information, see https://docs.prefect.io/v3/develop/task-run-limits.
+    """
     # hydrate the input model into a full model
     concurrency_limit_model = schemas.core.ConcurrencyLimit(
         **concurrency_limit.model_dump()

src/prefect/server/api/concurrency_limits_v2.py

@@ -21,6 +21,11 @@ async def create_concurrency_limit_v2(
     concurrency_limit: actions.ConcurrencyLimitV2Create,
     db: PrefectDBInterface = Depends(provide_database_interface),
 ) -> schemas.core.ConcurrencyLimitV2:
+    """
+    Create a task run concurrency limit.
+
+    For more information, see https://docs.prefect.io/v3/develop/global-concurrency-limits.
+    """
     async with db.session_context(begin_transaction=True) as session:
         model = await models.concurrency_limits_v2.create_concurrency_limit(
             session=session, concurrency_limit=concurrency_limit

src/prefect/server/api/deployments.py

@@ -68,6 +68,8 @@ async def create_deployment(
 
     If the deployment has an active schedule, flow runs will be scheduled.
     When upserting, any scheduled runs from the existing deployment will be deleted.
+
+    For more information, see https://docs.prefect.io/v3/deploy.
     """
 
     data = deployment.model_dump(exclude_unset=True)

src/prefect/server/api/events.py

@@ -48,7 +48,11 @@ async def create_events(
     events: List[Event],
     ephemeral_request: bool = Depends(is_ephemeral_request),
 ) -> None:
-    """Record a batch of Events"""
+    """
+    Record a batch of Events.
+
+    For more information, see https://docs.prefect.io/v3/automate/events/events.
+    """
     if ephemeral_request:
         await EventsPipeline().process_events(events)
     else:

src/prefect/server/api/flow_run_notification_policies.py

@@ -25,6 +25,8 @@ async def create_flow_run_notification_policy(
 ) -> schemas.core.FlowRunNotificationPolicy:
     """
     Creates a new flow run notification policy.
+
+    For more information, see https://docs.prefect.io/v3/automate/events/automations-triggers#sending-notifications-with-automations.
     """
     async with db.session_context(begin_transaction=True) as session:
         return await models.flow_run_notification_policies.create_flow_run_notification_policy(

src/prefect/server/api/flow_run_states.py

@@ -26,6 +26,8 @@ async def read_flow_run_state(
 ) -> schemas.states.State:
     """
     Get a flow run state by id.
+
+    For more information, see https://docs.prefect.io/v3/develop/write-flows#final-state-determination.
     """
     async with db.session_context() as session:
         flow_run_state = await models.flow_run_states.read_flow_run_state(

src/prefect/server/api/flow_runs.py

@@ -74,6 +74,8 @@ async def create_flow_run(
     idempotency key already exists, the existing flow run will be returned.
 
     If no state is provided, the flow run will be created in a PENDING state.
+
+    For more information, see https://docs.prefect.io/v3/develop/write-flows.
     """
     # hydrate the input model into a full flow run / state model
     flow_run_object = schemas.core.FlowRun(

src/prefect/server/api/flows.py

@@ -27,6 +27,8 @@ async def create_flow(
 ) -> schemas.core.Flow:
     """Gracefully creates a new flow from the provided schema. If a flow with the
     same name already exists, the existing flow is returned.
+
+    For more information, see https://docs.prefect.io/v3/develop/write-flows.
     """
     # hydrate the input model into a full flow model
     flow = schemas.core.Flow(**flow.model_dump())

src/prefect/server/api/logs.py

@@ -20,7 +20,11 @@ async def create_logs(
     logs: List[schemas.actions.LogCreate],
     db: PrefectDBInterface = Depends(provide_database_interface),
 ) -> None:
-    """Create new logs from the provided schema."""
+    """
+    Create new logs from the provided schema.
+
+    For more information, see https://docs.prefect.io/v3/develop/logging.
+    """
     for batch in models.logs.split_logs_into_batches(logs):
         async with db.session_context(begin_transaction=True) as session:
             await models.logs.create_logs(session=session, logs=batch)

src/prefect/server/api/task_run_states.py

@@ -26,6 +26,8 @@ async def read_task_run_state(
 ) -> schemas.states.State:
     """
     Get a task run state by id.
+
+    For more information, see https://docs.prefect.io/v3/develop/write-tasks.
     """
     async with db.session_context() as session:
         task_run_state = await models.task_run_states.read_task_run_state(

src/prefect/server/api/task_runs.py

@@ -57,6 +57,8 @@ async def create_task_run(
     run will be returned.
 
     If no state is provided, the task run will be created in a PENDING state.
+
+    For more information, see https://docs.prefect.io/v3/develop/write-tasks.
     """
     # hydrate the input model into a full task run / state model
     task_run_dict = task_run.model_dump()

src/prefect/server/api/task_workers.py

@@ -20,7 +20,11 @@ async def read_task_workers(
         default=None, description="The task worker filter", embed=True
     ),
 ) -> List[TaskWorkerResponse]:
-    """Read active task workers. Optionally filter by task keys."""
+    """
+    Read active task workers. Optionally filter by task keys.
+
+    For more information, see https://docs.prefect.io/v3/develop/deferred-tasks.
+    """
 
     if task_worker_filter and task_worker_filter.task_keys:
         return await models.task_workers.get_workers_for_task_keys(

src/prefect/server/api/variables.py

@@ -57,6 +57,11 @@ async def create_variable(
     variable: actions.VariableCreate,
     db: PrefectDBInterface = Depends(provide_database_interface),
 ) -> core.Variable:
+    """
+    Create a variable.
+
+    For more information, see https://docs.prefect.io/v3/develop/variables.
+    """
     async with db.session_context(begin_transaction=True) as session:
         try:
             model = await models.variables.create_variable(