--- title: "Create cron job" method: POST path: "/v1/cron-jobs" tags: ["cron-jobs"] --- # Create cron job `POST /v1/cron-jobs` ## Request - Base URL: `https://api.patricia.app` (the document declares no server; this is the origin it was published from) - URL: `https://api.patricia.app/v1/cron-jobs` - Auth: HTTP bearer Create a new scheduled job, attributed to the requesting actor. ## Headers - `X-Tenant-Id` string, nullable ## Request body - CronJobCreateRequest: Cron create fields plus an optional server-validated channel selection. - `name` string, required - `schedule` string, nullable - `local_schedule` string, nullable - `timezone` string, nullable - `run_at` string, date-time, nullable - `kind_code` 'reminder' | 'task': What a fired ``CronJob`` does (plan 02 §6). ``reminder`` pings the originating conversation with the stored message (no agent run); ``task`` runs the stored prompt as a scheduled agent action and delivers the result back to that conversation. - `prompt` string, required - `condition_script` string, nullable - `enabled` boolean - `model` string - `cost_tier` string, nullable - `max_runs` integer, nullable - `delivery_channel_id` string, nullable - `declaration` CreationDeclaration - `task` TaskDeclaration, required - `purpose` string, required: One plain sentence. - `deliverables` string[]: Short plain phrases. - `lines` DeclaredLine[], required: In order; repeat entries for repeats. - `tool_name` string, required: Exact. - `pins` object: Targets; omit varying args. - `targets` object[]: Arg map/target instead of pins. - `short_summary` string, nullable - `call_arguments` object, nullable: Exact planned args. - `arguments` object - `reads` CreationReadScope[] - `tool_name` string, required - `principal_key` string, required - `source` string, required - `lines` CreationPermissionLineInput[], nullable - `tool_name` string, required - `arguments` object, required - `reads` CreationReadScope[] - `tool_name` string, required - `principal_key` string, required - `source` string, required - `item_binding` CreationItemBindingInput - `kind` 'none' | 'selected_target' | 'source_item' - `read_tool_name` string, nullable - `target_argument` string, nullable - `resource_namespace` string, nullable - `call_cap` integer - `item_cap` integer - `max_writes_per_run` integer ## Response `201` The created cron job. - CronJobCreateResponse: The create reply: the row, plus how the thing just created resolves its connections. Separate from the update reply because the field belongs to CREATION. On the shared model an edit receipt would report a task creation that did not happen. ``None`` for a REMINDER. A reminder never enters an agent run, so it uses no connections at all and the note would describe behaviour that does not occur. This varies by the KIND of row, never by what the caller can see: copy that changed with connection state would disclose that a hidden connection exists, which is the one thing this note must not do. - `id` string, uuid, required - `tenant_id` string, uuid, required - `name` string, required - `schedule` string, nullable - `local_schedule` string, nullable - `timezone` string, nullable - `run_at` string, date-time, nullable - `kind_code` 'reminder' | 'task', required: What a fired ``CronJob`` does (plan 02 §6). ``reminder`` pings the originating conversation with the stored message (no agent run); ``task`` runs the stored prompt as a scheduled agent action and delivers the result back to that conversation. - `delivery_conversation_id` string, uuid, nullable - `delivery_channel_id` string, nullable - `delivery_destination_kind` 'dm' | 'channel' | 'unknown_channel', nullable - `billing_skip_reason` 'no_credits' | 'subscription_inactive', nullable - `delivery_channel_name` string, nullable - `created_by_actor_id` string, uuid, nullable - `built_in_template_key` string, nullable - `viewer_may_change_instructions` boolean, nullable - `auto_approve_level` 'read_only' | 'read_and_write', nullable - `summary` string, nullable - `instructions` string, nullable - `instructions_author_actor_id` string, uuid, nullable - `prompt` string, required - `condition_script` string, nullable - `enabled` boolean, required - `model` string, required - `cost_tier` string, nullable - `locked_by` string, nullable - `lease_expires_at` string, date-time, nullable - `last_run_at` string, date-time, nullable - `next_run_at` string, date-time, nullable - `run_count` integer, required - `max_runs` integer, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required - `connection_scope_note` string, nullable - `creation_offer` CreationAttemptStatus: One permission-setup attempt for a saved task. - `attempt_id` string, uuid, required - `source_kind` 'task_cron' | 'event_trigger', required - `source_id` string, uuid, required - `state` 'unclaimed' | 'claimed' | 'completed' | 'failed' | 'superseded', required - `outcome` string, nullable, required - `candidate_id` string, uuid, nullable, required - `permission_active` boolean - `approved_permission` CreationApprovedPermission: The creator's live standing permission, separate from prepared details. - `grant_id` string, uuid, required - `tier` 'A' | 'B', required - `candidate_id` string, uuid, nullable, required - `instruction` string, required - `tool_names` string[], required - `external_account_id` string, required - `verified_principal` string, nullable, required - `fields` CreationCandidateField[], required - `name` string, required - `mode` string, required - `role` string, required - `cardinality` string, required - `element_type` string, nullable, required - `fixed` boolean, required - `value` unknown - `pin_reason` string, nullable, required - `max_items` integer, nullable, required - `reads` CreationApprovedRead[], required - `provider` string, required - `external_account_id` string, required - `principal_key` string, required - `source` string, required - `max_occurrences` integer, required - `max_actions` integer, required - `max_writes_per_run` integer, nullable, required - `expires_at` string, date-time, required - `lines` CreationCandidateLine[] - `line_id` string, required - `tool_name` string, required - `tool_ref` string, required - `account` CreationCandidateAccount, required - `provider` string, required - `external_account_id` string, required - `verified_principal` string, required - `connection_generation` integer, required - `fields` CreationCandidateField[], required - `name` string, required - `mode` string, required - `role` string, required - `cardinality` string, required - `element_type` string, nullable, required - `fixed` boolean, required - `value` unknown - `pin_reason` string, nullable, required - `max_items` integer, nullable, required - `call_cap` integer, required - `item_cap` integer, required - `item_binding` CreationItemBindingView, required - `kind` 'none' | 'selected_target' | 'source_item', required - `target_argument` string, nullable - `resource_namespace` string, nullable - `read` CreationCandidateRead - `account` CreationCandidateAccount, required - … - `principal_key` string, required - `source` string, required - `read_tool_ref` string, nullable - `read_schema_fingerprint` string, nullable - `extractor_code` string, nullable - `extractor_version` string, nullable - `projection_fingerprint` string, nullable - `toolkit_version` string, nullable - `normalization_changes` string[] - `repeat_scope` 'occurrence', nullable - `repeat_disclosure` string, nullable - `review` 'available' | 'unavailable' | 'expired', nullable ## Other responses - `400`: Bad request - `401`: Unauthorized - `403`: Forbidden. Inspect response body `code` for the specific reason (for example: PERMISSION_DENIED, EMAIL_NOT_VERIFIED, TENANT_ACCESS_REQUIRED, ROLE_UNRESOLVED) - `409`: Conflict - `422`: Validation error --- [API](https://skmtc.dev/patricia/apis/patricia-api.md) · [All operations](https://skmtc.dev/patricia/apis/patricia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/patricia/apis/patricia-api/revisions/0dfb44495ea1?raw)