Actions

API endpoints for various actions

Handle Action Requests

post

This endpoint provides a unified interface for performing various actions on pipelines, tasks, and related resources. Users can specify the desired action in the request body, and the API dynamically routes the request to the appropriate handler.

For detailed examples on how to use this endpoint, see Opsera API Documentation

---

AI Agent Guide: Pipeline Actions

This endpoint is the primary way to manage pipelines via MCP. Use it for running, stopping, resetting, updating, deleting, approving, and rejecting pipelines.

Quick Reference: Pipeline Actions

Action	Description	Request Format
run	Start pipeline execution	{ action: "run", type: "pipeline", version: 1, target: ["<pipeline_id>"] }
stop	Stop a running pipeline	{ action: "stop", type: "pipeline", version: 1, target: ["<pipeline_id>"] }
reset	Reset pipeline to initial state	{ action: "reset", type: "pipeline", version: 1, target: ["<pipeline_id>"] }
update	Update pipeline properties	{ action: "update", type: "pipeline", version: 1, target: "<pipeline_id>", settings: {...} }
delete	Delete a pipeline	{ action: "delete", type: "pipeline", version: 1, target: ["<pipeline_id>"] }
status	Get pipeline status	{ action: "status", type: "pipeline", version: 1, target: ["<pipeline_id>"] }
approve	Approve pipeline at approval gate	{ action: "approve", type: "pipeline", version: 1, target: ["<pipeline_id>"] }
reject	Reject pipeline at approval gate	{ action: "reject", type: "pipeline", version: 1, target: ["<pipeline_id>"], message: "..." }

AI Agent Best Practices

1. Always include all required fields: action, type, version, and target

2. Version is always 1: Use version: 1 for all current actions

3. Target format varies:

   • Batch operations (run, stop, reset, delete, status, approve, reject): Use array target: ["id1", "id2"]

   • Single update: Use string target: "id"

4. Get pipeline ID first: Use /api/v2/pipelines or status action to find pipeline IDs

5. Check status before actions: Use status action to verify pipeline state before run/stop/reset

Common AI Agent Workflows

Run a pipeline:

{ "action": "run", "type": "pipeline", "version": 1, "target": ["64d7c869b5760b001e46c1a2"] }

Stop a running pipeline:

{ "action": "stop", "type": "pipeline", "version": 1, "target": ["64d7c869b5760b001e46c1a2"] }

Reset a pipeline (clear run state):

{ "action": "reset", "type": "pipeline", "version": 1, "target": ["64d7c869b5760b001e46c1a2"] }

Update pipeline name/description:

{
  "action": "update",
  "type": "pipeline",
  "version": 1,
  "target": "64d7c869b5760b001e46c1a2",
  "settings": {
    "name": "New Pipeline Name",
    "description": "Updated description"
  }
}

Approve a pipeline waiting at approval gate:

{ "action": "approve", "type": "pipeline", "version": 1, "target": ["64d7c869b5760b001e46c1a2"] }

Reject a pipeline at approval gate with reason:

{ "action": "reject", "type": "pipeline", "version": 1, "target": ["64d7c869b5760b001e46c1a2"], "message": "Code review not completed" }

Clone Pipeline (Not a Direct Action)

There is no direct "clone" action. To clone a pipeline:

1. Get the pipeline using status action or GET request

2. Create a new pipeline using POST /api/v2/pipelines with the copied configuration

3. Modify the name to avoid duplicates

Example workflow:

1. Get source pipeline: { "action": "status", "type": "pipeline", "version": 1, "target": ["<source_id>"] }

2. Copy the pipeline object, change name, remove _id, createdAt, updatedAt

3. Create new pipeline: POST /api/v2/pipelines with the modified object

---

Supported Actions

• status: Check the current status of a resource

• create: Create a new resource or configuration

• update: Update an existing resource

• run: Execute or run a specific resource or process

• stop: Stop an ongoing process or execution

• reset: Reset a resource to its initial state

• delete: Delete a resource permanently

• approve: Approve a pipeline waiting at an approval gate

• reject: Reject a pipeline at an approval gate

Supported Types by Action

Action	Supported Types
status	task, pipeline
create	task, pipeline
update	task, pipeline
run	task, pipeline
stop	task, pipeline
reset	pipeline
delete	pipeline
approve	pipeline
reject	pipeline

---

Required Access

• Authentication: Bearer token in the Authorization header.

• Permissions: User must have appropriate roles and permissions to perform the action.

---

Process Details

• Request Validation:

  • Validates that the action parameter is provided and is supported.

  • Validates that the type parameter is supported for the specified action.

  • Ensures the request body contains all required parameters for the specified action and type.

• Action Handling:

  • Routes the request to the corresponding action handler based on action and type.

  • Processes the action based on the provided parameters.

• Audit Logging:

  • Logs the action performed for traceability and monitoring.

---

Important Notes!

• Supported Actions Only: If the provided action is not in the supported list, the request will return an error.

• Action-Specific Requirements: Each action has its own specific set of required parameters.

• Pipeline Actions: Most pipeline actions support batch operations (multiple pipeline IDs in one request).

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Body

application/json

actionstring · enumRequired

The action to be performed

Example: runPossible values:

typestring · enumRequired

The type of resource to act upon

Example: pipelinePossible values:

versionnumberRequired

The API version for the action

Example: 1

targetone ofOptionalExample: ["64d7c869b5760b001e46c1a2","64d7c869b5760b001e46c1a3"]

stringOptional

Single resource ID

or

string[]Optional

Array of resource IDs for batch operations

settingsobjectOptional

Additional settings required for update actions

Responses

200

The action was successfully processed.

application/json

or

400

Invalid or unsupported action request.

application/json

401

Unauthorized access - Missing or invalid token.

application/json

500

Internal server error.

application/json

post

/api/v2/actions

HTTPcURLJavaScriptPython

POST /api/v2/actions HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "action": "run",
  "type": "pipeline",
  "version": 1,
  "target": [
    "64d7c869b5760b001e46c1a2"
  ]
}

Run PipelineStop PipelineReset PipelineDelete PipelineUpdate PipelineGet Pipeline StatusBatch Run Multiple PipelinesApprove Pipeline at Approval GateReject Pipeline at Approval GateCreate a New PipelineCreate Multi-Step Pipeline with Dependencies

{
  "status": "success",
  "message": "Out of the 2 run requests, all have succeeded",
  "responses": [
    {
      "id": "64d7c869b5760b001e46c1a2",
      "name": "Production Pipeline",
      "status": "success",
      "message": "Pipeline run initiated successfully"
    },
    {
      "id": "64d7c869b5760b001e46c1a3",
      "name": "Staging Pipeline",
      "status": "success",
      "message": "Pipeline run initiated successfully"
    }
  ]
}