Pipeline Parameters

Endpoints for managing pipeline parameters.

Pipeline parameters allow you to define reusable, configurable values that can be referenced across pipeline steps. This enables dynamic pipeline configuration without modifying the pipeline definition itself.

---

Key Features

• Centralized Configuration: Define parameters once, use across multiple steps

• Role-Based Access: Parameters respect pipeline access controls

• Secure Value Storage: Sensitive parameter values can be stored securely

• Dynamic Pipeline Execution: Override parameter values at runtime

---

Common Use Cases

• Environment Variables: Store environment-specific configurations (dev, staging, prod)

• Secrets Management: Secure storage of API keys, credentials, tokens

• Build Configuration: Version numbers, build flags, feature toggles

• Deployment Targets: Target environment URLs, cluster names, namespaces

---

Parameter Structure

Each pipeline parameter includes:

• _id: Unique identifier (MongoDB ObjectId)

• pipelineId: Associated pipeline ID

• name: Human-readable parameter name

• value: The parameter value (can be string, number, boolean, or object)

• type: Parameter type (string, number, boolean, secret)

• description: Optional description for documentation

• createdAt: Timestamp of creation

• updatedAt: Timestamp of last update

Get All Parameters for a Pipeline

get

Retrieves all pipeline parameters associated with a specific pipeline ID.

This endpoint returns an array of all parameters defined for the pipeline, along with a count of total parameters. Parameters are returned based on the user's role-based access permissions for the pipeline.

Access Control

• User must have read access to the associated pipeline

• Returns only parameters the user is authorized to view

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.

Path parameters

pipelineIdstringRequired

The MongoDB ObjectId of the pipeline

Example: 602242ea6fc729aa1de8608cPattern: ^[a-zA-Z0-9]{24}$

Responses

200

Successfully retrieved pipeline parameters

application/json

countintegerOptional

Total number of parameters returned

Example: 3

400

Bad Request - Invalid pipeline ID format

401

Authentication failed

403

Access denied - User lacks permission to view pipeline parameters

404

Pipeline not found

500

Internal server error

get

/api/v2/parameters/pipeline/{pipelineId}

HTTPcURLJavaScriptPython

GET /api/v2/parameters/pipeline/{pipelineId} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 2,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "pipelineId": "602242ea6fc729aa1de8608c",
      "name": "DEPLOY_ENV",
      "value": "production",
      "type": "string",
      "description": "Target deployment environment"
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "pipelineId": "602242ea6fc729aa1de8608c",
      "name": "FEATURE_FLAG",
      "value": "true",
      "type": "boolean",
      "description": "Enable new feature"
    }
  ]
}

Create a Pipeline Parameter

post

Creates a new parameter for the specified pipeline.

Pipeline parameters provide a way to store and manage configuration values that can be referenced by pipeline steps during execution.

Parameter Types

• string: Text values (default type)

• number: Numeric values

• boolean: True/false values

• secret: Sensitive values stored securely (masked in logs)

Naming Conventions

• Use uppercase with underscores for environment-variable-style names (e.g., DEPLOY_ENV, API_KEY)

• Names must be unique within a pipeline

• Names should be descriptive and follow your organization's conventions

Access Control

• User must have write access to the associated pipeline

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.

Path parameters

pipelineIdstringRequired

The MongoDB ObjectId of the pipeline

Example: 602242ea6fc729aa1de8608cPattern: ^[a-zA-Z0-9]{24}$

Body

application/json

namestringRequired

Parameter name (must be unique within the pipeline)

Example: DEPLOY_ENV

valuestringRequired

Parameter value

Example: production

typestring · enumOptional

Parameter type (defaults to "string" if not provided)

Example: stringPossible values:

descriptionstringOptional

Optional description of the parameter

Example: Target deployment environment

Responses

200

Parameter created successfully

application/json

400

Bad Request - Invalid input or duplicate parameter name

401

Authentication failed

403

Access denied - User lacks permission to create pipeline parameters

404

Pipeline not found

500

Internal server error

post

/api/v2/parameters/pipeline/{pipelineId}

HTTPcURLJavaScriptPython

POST /api/v2/parameters/pipeline/{pipelineId} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 104

{
  "name": "DEPLOY_ENV",
  "value": "production",
  "type": "string",
  "description": "Target deployment environment"
}

String parameterSecret parameterBoolean parameter

{
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "pipelineId": "602242ea6fc729aa1de8608c",
    "name": "DEPLOY_ENV",
    "value": "production",
    "type": "string",
    "description": "Target deployment environment",
    "createdAt": "2026-01-18T10:30:00.000Z",
    "updatedAt": "2026-01-18T10:30:00.000Z"
  }
}

Get a Pipeline Parameter by ID

get

Retrieves a single pipeline parameter by its unique identifier.

This endpoint returns the complete parameter object including all metadata. For retrieving only the parameter value, use the /api/v2/parameters/{parameterId}/value endpoint.

Access Control

• User must have read access to the pipeline that contains this parameter

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.

Path parameters

parameterIdstringRequired

The MongoDB ObjectId of the pipeline parameter

Example: 507f1f77bcf86cd799439011Pattern: ^[a-zA-Z0-9]{24}$

Responses

200

Successfully retrieved pipeline parameter

application/json

400

Bad Request - Invalid parameter ID format

401

Authentication failed

403

Access denied - User lacks permission to view this parameter

404

Parameter not found

500

Internal server error

get

/api/v2/parameters/{parameterId}

HTTPcURLJavaScriptPython

GET /api/v2/parameters/{parameterId} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "pipelineId": "602242ea6fc729aa1de8608c",
    "name": "DEPLOY_ENV",
    "value": "production",
    "type": "string",
    "description": "Target deployment environment",
    "createdAt": "2026-01-18T10:30:00.000Z",
    "updatedAt": "2026-01-18T10:30:00.000Z"
  }
}

Update a Pipeline Parameter

put

Updates an existing pipeline parameter by its unique identifier.

This endpoint allows you to modify the parameter's name, value, type, or description. All fields in the request body will be used to update the parameter.

Update Behavior

• Partial updates are supported - only include fields you want to change

• The parameter ID and pipelineId cannot be changed

• Changing the type may affect how the value is interpreted by pipeline steps

Access Control

• User must have write access to the pipeline that contains this parameter

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.

Path parameters

parameterIdstringRequired

The MongoDB ObjectId of the pipeline parameter

Example: 507f1f77bcf86cd799439011Pattern: ^[a-zA-Z0-9]{24}$

Body

application/json

namestringRequired

Parameter name (must be unique within the pipeline)

Example: DEPLOY_ENV

valuestringRequired

Parameter value

Example: production

typestring · enumOptional

Parameter type (defaults to "string" if not provided)

Example: stringPossible values:

descriptionstringOptional

Optional description of the parameter

Example: Target deployment environment

Responses

200

Parameter updated successfully

application/json

400

Bad Request - Invalid input or parameter ID format

401

Authentication failed

403

Access denied - User lacks permission to update this parameter

404

Parameter not found

500

Internal server error

put

/api/v2/parameters/{parameterId}

HTTPcURLJavaScriptPython

PUT /api/v2/parameters/{parameterId} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 122

{
  "name": "DEPLOY_ENV",
  "value": "staging",
  "type": "string",
  "description": "Target deployment environment - updated to staging"
}

Update parameter valueUpdate description only

{
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "pipelineId": "602242ea6fc729aa1de8608c",
    "name": "DEPLOY_ENV",
    "value": "staging",
    "type": "string",
    "description": "Target deployment environment - updated to staging",
    "createdAt": "2026-01-18T10:30:00.000Z",
    "updatedAt": "2026-01-18T12:45:00.000Z"
  }
}

Delete a Pipeline Parameter

delete

Deletes a pipeline parameter by its unique identifier.

This operation is permanent and cannot be undone. Any pipeline steps that reference this parameter will need to be updated to remove the reference or the pipeline execution may fail.

Important Considerations

• Irreversible: Deletion is permanent

• Pipeline Impact: Ensure no active pipeline steps reference this parameter

• Audit Trail: Deletion is logged for audit purposes

Access Control

• User must have write access to the pipeline that contains this parameter

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.

Path parameters

parameterIdstringRequired

The MongoDB ObjectId of the pipeline parameter to delete

Example: 507f1f77bcf86cd799439011Pattern: ^[a-zA-Z0-9]{24}$

Responses

200

Parameter deleted successfully

application/json

400

Bad Request - Invalid parameter ID format

401

Authentication failed

403

Access denied - User lacks permission to delete this parameter

404

Parameter not found

500

Internal server error

delete

/api/v2/parameters/{parameterId}

HTTPcURLJavaScriptPython

DELETE /api/v2/parameters/{parameterId} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "pipelineId": "602242ea6fc729aa1de8608c",
    "name": "DEPLOY_ENV",
    "value": "production",
    "type": "string",
    "description": "Target deployment environment"
  }
}

Get Pipeline Parameter Value Only

get

Retrieves only the value of a pipeline parameter by its unique identifier.

This endpoint returns just the parameter value without the full parameter metadata. Use this for lightweight value retrieval during pipeline execution or when only the value is needed.

Use Cases

• Pipeline Execution: Quick value lookup during step execution

• Script Integration: Retrieve values for external scripts or tools

• Validation: Verify parameter values before pipeline runs

Comparison with Full Parameter Endpoint

• GET /api/v2/parameters/{parameterId} - Returns complete parameter object

• GET /api/v2/parameters/{parameterId}/value - Returns only the value (this endpoint)

Access Control

• User must have read access to the pipeline that contains this parameter

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.

Path parameters

parameterIdstringRequired

The MongoDB ObjectId of the pipeline parameter

Example: 507f1f77bcf86cd799439011Pattern: ^[a-zA-Z0-9]{24}$

Responses

200

Successfully retrieved parameter value

application/json

dataone ofOptional

The parameter value

stringOptional

or

numberOptional

or

booleanOptional

or

objectOptional

400

Bad Request - Invalid parameter ID format

401

Authentication failed

403

Access denied - User lacks permission to view this parameter

404

Parameter not found

500

Internal server error

get

/api/v2/parameters/{parameterId}/value

HTTPcURLJavaScriptPython

GET /api/v2/parameters/{parameterId}/value HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "production"
}