# Augmented Operations Management API


## Overview

This API provides backend services for the Augmented Decision Making application, focusing on the efficient scheduling and assignment of tasks **Operations** to a given **Resources**.

The system models the following key entities:
*   **Locations:** Representing physical areas
*   **Resources:** Specific assignable assets within a location.
*   **Tasks:** Represent individual events, jobs. Tasks include detailed time information (planned, expected, actual) and model uncertainty using statistical parameters (sigma, skew factor, distribution mean/earliest/latest). Tasks also support versioning to track updates.
*   **Operations:** Represent a complete operation, linking an inbound task to an outbound task. Operations contain relevant metadata.
*   **Assignments:** Link an Operation to a specific Resource for a given time period.
*   **Tags:** Can be used to restrict possible assignments as well as indicate preferences or penalties.
*   **Rules:** Can be used to specify preferences or penalties in conjunction with the tagging mechanism.

## Core Functionality

The API enables users and automated systems to:

1.  **Manage Data:** Perform CRUD operations on Locations, Resources, Tasks, Operations, and Assignments.
2.  **Track Operations Times:** Handle various time representations and update task details, including imposing delays. Task updates create new versions, preserving history.
3.  **Assignments:** Assign or reassign operation to resources.
4.  **Detect Conflicts:** Identify situations where an assigned conflicting (overlapping) with another based on their expected time windows.
5.  **Resolve Conflicts:** Offer mechanisms to resolve individual scheduling conflicts through AI.
6.   **Optimize Globally:** Offer global optimization of the schedule using various solvers to minimize conflicts and reassignments while optimizing for rules.
7.  **AI Assistance:** Interact with an AI agent (via the `/agent/` endpoint) using natural language to query the schedule, identify conflicts, request moves, or trigger conflict resolution processes. The agent utilizes specialized tools to interact with the system's state.
8.  **Real-time Updates:** Delivers real-time notifications about changes to Assignments and Operations via WebSockets to subscribed clients.
9.  **Virtual State Management:** Allows temporary modifications to the schedule (virtual assignments) for "what-if" scenarios or agent-driven planning before potentially persisting changes.
    

Version: 1.0.0

## Servers

Acceptance Environment
```
https://api.acc.adm.wearetransformers.nl
```

## Security

### tokenAuth

Token-based authentication with required prefix "Token"

Type: apiKey
In: header
Name: Authorization

## Download OpenAPI description

[Augmented Operations Management API](https://docs.adm.wearetransformers.nl/_bundle/apis/schema.yaml)

## Users

User management (authentication, current user details).

### Get preferences for a planning

 - [GET /v1/plannings/{id}/preferences/](https://docs.adm.wearetransformers.nl/apis/schema/users/v1_plannings_preferences_retrieve.md): Returns the current user's preferences for this planning. Auto-creates empty preferences if none exist.

### Save preferences for a planning

 - [PUT /v1/plannings/{id}/preferences/](https://docs.adm.wearetransformers.nl/apis/schema/users/v1_plannings_preferences_update.md): Creates or replaces the current user's preferences for this planning.

### Get Current User

 - [GET /v1/user/current/](https://docs.adm.wearetransformers.nl/apis/schema/users/v1_user_current_retrieve.md): Retrieves the details of the currently authenticated user.

## Locations

Managing locations and viewing their associated resources.

### Creates a new location

 - [POST /v1/locations/](https://docs.adm.wearetransformers.nl/apis/schema/locations/v1_locations_create.md): Creates a new location.

### Updates an existing location

 - [PATCH /v1/locations/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/locations/v1_locations_partial_update.md): Updates an existing location.

### Get all locations and resources for a planing

 - [GET /v1/plannings/{id}/locations/](https://docs.adm.wearetransformers.nl/apis/schema/locations/v1_plannings_locations_list.md): List a nested result of locations and resources for a planning.

## Resources

Managing resources (CRUD, listing).

### Get all resources for a planning

 - [GET /v1/plannings/{id}/resources/](https://docs.adm.wearetransformers.nl/apis/schema/resources/v1_plannings_resources_list.md): List all resources for a planning.

### Create Resource

 - [POST /v1/resources/](https://docs.adm.wearetransformers.nl/apis/schema/resources/v1_resources_create.md): Creates a new resource associated with a location.

### Partially Update Resource

 - [PATCH /v1/resources/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/resources/v1_resources_partial_update.md): Updates specific fields of a resource (e.g., name, ordering, tags).

### Delete Resource

 - [DELETE /v1/resources/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/resources/v1_resources_destroy.md): Marks a resource as deleted (soft delete). Also deactivates any active assignments associated with this resource.

## Operations

Managing operations. Includes CRUD and listing with time/version filters.

### Create Operation

 - [POST /v1/operations/](https://docs.adm.wearetransformers.nl/apis/schema/operations/v1_operations_create.md): Creates operation.

### Retrieve Operation

 - [GET /v1/operations/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/operations/v1_operations_retrieve.md): Retrieves details of a specific operation by its UUID.

### Partially Update Operation

 - [PATCH /v1/operations/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/operations/v1_operations_partial_update.md): Updates specific fields of an operation, such as its metadata or task details (which creates new task versions).

### Delete Operation

 - [DELETE /v1/operations/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/operations/v1_operations_destroy.md): Soft-deletes an operation by marking its active state as deleted.

### Get assignment for this operation

 - [GET /v1/operations/{id}/assignment/](https://docs.adm.wearetransformers.nl/apis/schema/operations/v1_operations_assignment_retrieve.md): Returns the active assignment for the operation identified by pk.
404 if the operation is currently unassigned.

### Get task history for this operation

 - [GET /v1/operations/{id}/tasks/](https://docs.adm.wearetransformers.nl/apis/schema/operations/v1_operations_tasks_list.md): Extends WorkspaceMixin with serializer context for workspace-aware CRUD.

### Create Operations in bulk

 - [POST /v1/operations/bulk/](https://docs.adm.wearetransformers.nl/apis/schema/operations/v1_operations_bulk_create.md): Creates operations in bulk.

### Bulk partial update Operations

 - [PATCH /v1/operations/bulk/](https://docs.adm.wearetransformers.nl/apis/schema/operations/v1_operations_bulk_partial_update.md): Perform a bulk update for multiple operations. This endpoint is atomic; either all updates succeed or none do.

### Get all operations for a planning

 - [GET /v1/plannings/{id}/operations/](https://docs.adm.wearetransformers.nl/apis/schema/operations/v1_plannings_operations_list.md): List operations, optionally filtering by a time window.

Query params:
- start_timestamp / end_timestamp (Unix seconds, UTC). Both required to apply the window filter.
- range_field (one of):
    • expectedTime95Interval → inbound p05 ≤ end AND outbound p95 ≥ start
    • expectedTime90Interval → inbound p10 ≤ end AND outbound p90 ≥ start
    • expectedTime           → inbound expected ≤ end AND outbound expected ≥ start
    • scheduledTime           → inbound scheduled ≤ end AND outbound scheduled ≥ start

### Search operations (simple)

 - [POST /v1/plannings/{id}/operations/search/](https://docs.adm.wearetransformers.nl/apis/schema/operations/v1_plannings_operations_search_create.md): Search within a planning by external_id.

## Tasks

Updating details (time, uncertainty) of individual tasks within operations.

### List tasks by external_id

 - [GET /v1/plannings/{id}/tasks/](https://docs.adm.wearetransformers.nl/apis/schema/tasks/v1_plannings_tasks_list.md): List tasks for a planning filtered by external_id. The external_id parameter is required. Supports workspace overlay.

### Create task

 - [POST /v1/tasks/](https://docs.adm.wearetransformers.nl/apis/schema/tasks/v1_tasks_create.md): Create a task without an operation. The task can be linked to an operation later. Supports workspace overlay.

### Retrieve Task

 - [GET /v1/tasks/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/tasks/v1_tasks_retrieve.md): Get a single task by ID.

### Update Task

 - [PATCH /v1/tasks/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/tasks/v1_tasks_partial_update.md): Update task fields (expected times, tags, etc.). Supports workspace overlay.

### Delete Task

 - [DELETE /v1/tasks/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/tasks/v1_tasks_destroy.md): Soft-delete a task by marking its state as deleted. Supports workspace overlay.

## Assignments

Managing the assignment of operations to resources (CRUD, bulk operations, deactivation, listing per operation).

### Create Assignment

 - [POST /v1/assignments/](https://docs.adm.wearetransformers.nl/apis/schema/assignments/v1_assignments_create.md): Creates a new assignment (with its parts) for an operation. If X-Workspace-Id header is set, creates in workspace (branch-on-first-write). Otherwise creates on mainline and deactivates any existing active assignment.

### Deactivate an assignment

 - [POST /v1/assignments/{id}/deactivate/](https://docs.adm.wearetransformers.nl/apis/schema/assignments/v1_assignments_deactivate_create.md): Deactivates the active assignment for an operation. If X-Workspace-Id header is set, creates a tombstone in the workspace instead.

### Bulk create assignments

 - [POST /v1/assignments/bulk/](https://docs.adm.wearetransformers.nl/apis/schema/assignments/v1_assignments_bulk_create.md): Create multiple assignments in a single request.

### v1_plannings_assignments_list

 - [GET /v1/plannings/{id}/assignments/](https://docs.adm.wearetransformers.nl/apis/schema/assignments/v1_plannings_assignments_list.md): Extends WorkspaceMixin with serializer context for workspace-aware CRUD.

## Conflict Resolution

Resolving specific scheduling conflicts using heuristic search methods (streaming and non-streaming).

### Resolve Conflict (Streaming)

 - [POST /v1/operations/{id}/resolve-conflict-stream/part/{part_pk}/](https://docs.adm.wearetransformers.nl/apis/schema/conflict-resolution/v1_operations_resolve_conflict_stream_part_create.md): Analyzes conflicts for a specific operation and streams potential resolution strategies (sets of moves) as NDJSON. Requires virtual state context.

### Resolve Conflict (Non-Streaming)

 - [POST /v1/operations/{id}/resolve-conflict/part/{part_pk}/](https://docs.adm.wearetransformers.nl/apis/schema/conflict-resolution/v1_operations_resolve_conflict_part_create.md): Analyzes conflicts for a specific operation within its time window and returns a list of potential resolution strategies (sets of moves). Requires virtual state context.

## Optimization

Globally optimizing the schedule using one of the solvers to minimize conflicts and reassignments while optimizing for rules.

### Get all tasks for a planning

 - [GET /v1/plannings/{id}/optimization-task-results/](https://docs.adm.wearetransformers.nl/apis/schema/optimization/v1_plannings_optimization_task_results_list.md): Get all tasks for a planning.

### Update an optimization task.

 - [PATCH /v1/plannings/{id}/optimization-task-results/{task_id}/](https://docs.adm.wearetransformers.nl/apis/schema/optimization/v1_plannings_optimization_task_results_partial_update.md): Updates an optimization task. Warning: this cannot be used to change the parameters of already running or starting tasks.

### Delete an optimization task result

 - [DELETE /v1/plannings/{id}/optimization-task-results/{task_id}/](https://docs.adm.wearetransformers.nl/apis/schema/optimization/v1_plannings_optimization_task_results_destroy.md): Deletes an optimization task result. Warning: this will not kill your running task in the background.

### Get the solver data for a task

 - [GET /v1/plannings/{id}/optimization-task-results/{task_id}/data/](https://docs.adm.wearetransformers.nl/apis/schema/optimization/v1_plannings_optimization_task_results_data_retrieve.md): Get the solver data for a task.

### Submit final optimization result

 - [POST /v1/plannings/{id}/optimization-task-results/{task_id}/result/](https://docs.adm.wearetransformers.nl/apis/schema/optimization/v1_plannings_optimization_task_results_result_create.md): Webhook endpoint for the solver to submit the final result payload. Requires Webhook auth. Body should be the raw solver output JSON.

### Optimize a plan

 - [POST /v1/plannings/{id}/optimize/](https://docs.adm.wearetransformers.nl/apis/schema/optimization/v1_plannings_optimize_create.md): Start a task to optimize all assignments in a planning.

## Organizations & Planning

Managing the plannings and organizations you have access to.

### Get all organizations for the authenticated user

 - [GET /v1/organizations/](https://docs.adm.wearetransformers.nl/apis/schema/organizations-and-planning/v1_organizations_list.md): Get all organizations for the authenticated user.

### Get all plannings for an organization

 - [GET /v1/organizations/{org_pk}/plannings/](https://docs.adm.wearetransformers.nl/apis/schema/organizations-and-planning/v1_organizations_plannings_list.md): Get all plannings for an organization.

### Creates a new planning for an organization

 - [POST /v1/organizations/{org_pk}/plannings/](https://docs.adm.wearetransformers.nl/apis/schema/organizations-and-planning/v1_organizations_plannings_create.md): Creates a new planning associated with an organization.

### Updates a planning

 - [PATCH /v1/organizations/{org_pk}/plannings/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/organizations-and-planning/v1_organizations_plannings_partial_update.md): Updates an existing planning.

### Delete a planning

 - [DELETE /v1/organizations/{org_pk}/plannings/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/organizations-and-planning/v1_organizations_plannings_destroy.md): Deletes a planning and all associated resources.

### Get all metadata for a planning

 - [GET /v1/plannings/{id}/meta/](https://docs.adm.wearetransformers.nl/apis/schema/organizations-and-planning/v1_plannings_meta_retrieve.md): Gets all metadata for a planning like solvers etc.

## AI Agent

Interacting with the conversational AI assistant for planning and queries.

### Generate responses using an agent

 - [POST /v1/plannings/{id}/agent/](https://docs.adm.wearetransformers.nl/apis/schema/ai-agent/v1_plannings_agent_create.md): Accepts chat history input and streams agent-generated responses in NDJSON format.

## Utility

Utility endpoints, such as generating schedule visualizations.

### Bulk upload operations for one or more plannings

 - [POST /v1/plannings/{id}/operations/bulk-upload/](https://docs.adm.wearetransformers.nl/apis/schema/utility/v1_plannings_operations_bulk_upload_create.md): Allows uploading multiple operations to an organization and linking them to one or more plannings via their IDs.

## Tags

Our mechanism for indicating constraints, penalties or preferences.

### Get all tags for a planning

 - [GET /v1/plannings/{id}/tags/](https://docs.adm.wearetransformers.nl/apis/schema/tags/v1_plannings_tags_list.md): Lists all tags for a planning.

### Creates a new tag

 - [POST /v1/tags/](https://docs.adm.wearetransformers.nl/apis/schema/tags/v1_tags_create.md): Creates a new tag.

### v1_tags_partial_update

 - [PATCH /v1/tags/{uuid}/](https://docs.adm.wearetransformers.nl/apis/schema/tags/v1_tags_partial_update.md): Helpers for workspace-aware StableEntity CRUD writes.

Contract:
- Reads may target any non-archived workspace (middleware validated).
- Writes must target a DRAFT workspace (enforced via get_workspace_for_write()).

### Delete a tag

 - [DELETE /v1/tags/{uuid}/](https://docs.adm.wearetransformers.nl/apis/schema/tags/v1_tags_destroy.md): Deletes a tag.

## Rules

Can be used together with Tags to specify preferences or penalties.

### Get all rules for a planning

 - [GET /v1/plannings/{id}/rules/](https://docs.adm.wearetransformers.nl/apis/schema/rules/v1_plannings_rules_list.md): Lists all rules for a planning. Note that while tags are bound to an organization, rules are planning specific. This distinction is there because the same resource can be used in multiple plannings.

### Creates a new rule

 - [POST /v1/rules/](https://docs.adm.wearetransformers.nl/apis/schema/rules/v1_rules_create.md): Creates a new rule.

### Partially update a rule

 - [PATCH /v1/rules/{uuid}/](https://docs.adm.wearetransformers.nl/apis/schema/rules/v1_rules_partial_update.md): Updates specific fields of a rule.

### Delete a rule

 - [DELETE /v1/rules/{uuid}/](https://docs.adm.wearetransformers.nl/apis/schema/rules/v1_rules_destroy.md): Deletes a rule.

### Validates a rule without creating one

 - [POST /v1/rules/validate/](https://docs.adm.wearetransformers.nl/apis/schema/rules/v1_rules_validate_create.md): Validates a rule without creating one.

## Authentication

### auth_internal_docs_only_token_claims_retrieve

 - [GET /auth/internal/docs-only/token-claims/](https://docs.adm.wearetransformers.nl/apis/schema/authentication/auth_internal_docs_only_token_claims_retrieve.md): Schema for the custom JWT claims included in access tokens. Docs-only endpoint; not used by the application at runtime.

### auth_login_create

 - [POST /auth/login/](https://docs.adm.wearetransformers.nl/apis/schema/authentication/auth_login_create.md): Takes a set of user credentials and returns an access and refresh JSON web
token pair to prove the authentication of those credentials.

### auth_logout_create

 - [POST /auth/logout/](https://docs.adm.wearetransformers.nl/apis/schema/authentication/auth_logout_create.md)

### Exchange OIDC LoginGrant code for JWTs

 - [POST /auth/oidc/exchange](https://docs.adm.wearetransformers.nl/apis/schema/authentication/oidc_exchange.md): Exchanges a one-time LoginGrant code produced by the SPA OIDC callback for a pair of JWT access/refresh tokens and the current user payload. The code is single-use and expires after a short time window.

### auth_refresh_create

 - [POST /auth/refresh/](https://docs.adm.wearetransformers.nl/apis/schema/authentication/auth_refresh_create.md): Takes a refresh type JSON web token and returns an access type JSON web
token if the refresh token is valid.

## Entity History

### Get entity version history

 - [GET /v1/{entity_type}/{entity_id}/history/](https://docs.adm.wearetransformers.nl/apis/schema/entity-history/v1_history_retrieve.md): Returns the version history for a specific entity instance.

        Shows all historical states with timestamps, change authors, and
        field-level diffs between versions.

        If X-Workspace-Id header is provided, includes workspace draft
        changes merged with mainline history. Workspace drafts appear
        alongside mainline states (not replacing them).

## Operation Groups

### Creates a new operation group

 - [POST /v1/operation-groups/](https://docs.adm.wearetransformers.nl/apis/schema/operation-groups/v1_operation_groups_create.md): Creates a new operation group associated with a planning.

### Get all operations in an operation group

 - [GET /v1/operation-groups/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/operation-groups/v1_operation_groups_retrieve.md): Lists all operations in an operation group.

### Update an operation group

 - [PATCH /v1/operation-groups/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/operation-groups/v1_operation_groups_partial_update.md): Updates specific fields of the operation group.

### Remove an operation group

 - [DELETE /v1/operation-groups/{id}/](https://docs.adm.wearetransformers.nl/apis/schema/operation-groups/v1_operation_groups_destroy.md): Removes a grouping of operations. Leaves the operations itself untouched.

### Get all operation groups for a given planning

 - [GET /v1/plannings/{id}/operation-groups/](https://docs.adm.wearetransformers.nl/apis/schema/operation-groups/v1_plannings_operation_groups_list.md): Gets all operations in an operation group for a given planning.

## Assignment History

### Get operation assignment history

 - [GET /v1/operations/{operation_id}/assignments/history/](https://docs.adm.wearetransformers.nl/apis/schema/assignment-history/v1_operations_assignments_history_retrieve.md): Returns the assignment version history for a specific operation.

        Shows all historical assignment states with timestamps, who made
        the assignment, and field-level diffs between versions.

        If X-Workspace-Id header is provided, includes workspace draft
        assignments merged with mainline history. Workspace drafts appear
        alongside mainline assignments (not replacing them).

## Plannings

### List planning changesets (timeline)

 - [GET /v1/plannings/{id}/changesets/](https://docs.adm.wearetransformers.nl/apis/schema/plannings/v1_plannings_changesets_retrieve.md): Returns compact changeset summaries for this planning (timestamp, status, source, and counts). Use the changeset detail endpoint for full per-entity diffs.

### Get planning changeset details

 - [GET /v1/plannings/{id}/changesets/{change_id}/](https://docs.adm.wearetransformers.nl/apis/schema/plannings/v1_plannings_changesets_retrieve_2.md): Returns one changeset with full per-entity diffs for AuditLog expansion.

### Get planning metrics

 - [GET /v1/plannings/{id}/metrics/](https://docs.adm.wearetransformers.nl/apis/schema/plannings/v1_plannings_metrics_retrieve.md): Get metrics for the planning at a specific point in time. Use change_id to get metrics at a specific changeset (historical state). Use mainline=true to explicitly get mainline metrics (ignores workspace header). Omit both for current metrics (workspace if header provided, mainline otherwise).

## Workspaces

### List workspaces for a planning

 - [GET /v1/plannings/{id}/workspaces/](https://docs.adm.wearetransformers.nl/apis/schema/workspaces/v1_plannings_workspaces_list.md): Returns all workspaces (draft, merged, archived) for the planning.

### Create a new workspace

 - [POST /v1/plannings/{id}/workspaces/](https://docs.adm.wearetransformers.nl/apis/schema/workspaces/v1_plannings_workspaces_create.md): Creates a new draft workspace for the planning.

### Get workspace details

 - [GET /v1/plannings/{id}/workspaces/{workspace_pk}/](https://docs.adm.wearetransformers.nl/apis/schema/workspaces/v1_plannings_workspaces_retrieve.md): Returns details for a specific workspace.

### Update workspace

 - [PATCH /v1/plannings/{id}/workspaces/{workspace_pk}/](https://docs.adm.wearetransformers.nl/apis/schema/workspaces/v1_plannings_workspaces_partial_update.md): Updates workspace name or description.

### Archive workspace

 - [DELETE /v1/plannings/{id}/workspaces/{workspace_pk}/](https://docs.adm.wearetransformers.nl/apis/schema/workspaces/v1_plannings_workspaces_destroy.md): Archives a workspace (soft delete). Archived workspaces cannot be modified.

### Undo a specific workspace changeset

 - [POST /v1/plannings/{id}/workspaces/{workspace_pk}/changesets/{change_id}/undo/](https://docs.adm.wearetransformers.nl/apis/schema/workspaces/v1_plannings_workspaces_changesets_undo_create.md): ViewSet for managing workspaces within a planning.

Workspaces allow users to make draft changes to assignments, operations,
and other planning data without affecting the mainline state. Changes
can be merged to mainline when ready.

### Get workspace diff (vs mainline)

 - [GET /v1/plannings/{id}/workspaces/{workspace_pk}/diff/](https://docs.adm.wearetransformers.nl/apis/schema/workspaces/v1_plannings_workspaces_diff_retrieve.md): Returns a summary of changes introduced by this workspace compared to mainline. Primarily used by the frontend AuditLog.

### Discard workspace changes

 - [POST /v1/plannings/{id}/workspaces/{workspace_pk}/discard/](https://docs.adm.wearetransformers.nl/apis/schema/workspaces/v1_plannings_workspaces_discard_create.md): Discards all workspace changes without merging.
        This operation:
        1. Closes all workspace state rows (marks as deleted)
        2. Updates workspace status to 'archived'

### Merge workspace to mainline

 - [POST /v1/plannings/{id}/workspaces/{workspace_pk}/merge/](https://docs.adm.wearetransformers.nl/apis/schema/workspaces/v1_plannings_workspaces_merge_create.md): Merges all workspace changes to mainline.
        This operation:
        1. Copies all workspace state rows to mainline (workspace=None)
        2. Closes the workspace state rows
        3. Updates workspace status to 'merged'
        Requires mainline write permission.