Tools

API endpoints for discovering and listing registered tools for pipeline configuration. These endpoints help AI agents and automation tools discover available tool identifiers, registered tool instances, and SCM repositories/branches.

Get Available Tool Identifiers

get

Returns a list of available tool identifiers that can be used for pipeline steps. Results are filtered based on user roles and organization's product SKU entitlements.

Tool identifiers represent types of tools that can be configured in pipeline steps. Common identifiers include:

SCM: github, gitlab, bitbucket, azure-devops
Security: snyk, sonar, fortify, twistlock, anchore-scan
Build: jenkins, npm, run_script, maven
Deploy: helm, terraform, aws_deploy, argo
Container: docker-push, docker_cli, azure_acr_push
Approval: approval, user-action

AI Agent Workflow

This is typically the first endpoint to call when building a pipeline:

Call this endpoint to discover available tool types
Filter identifiers relevant to your pipeline needs
For each identifier, call /api/v2/tools/registry to find registered instances
Get configuration requirements from /api/v2/pipelines/step-metadata
Build pipeline configuration and validate with /api/v2/pipelines/validate

Entitlement Filtering

If your organization has product SKU entitlements enabled, only tool identifiers that are entitled for your organization will be returned. Otherwise, all role-restricted tool identifiers are returned.

Query Parameters

Use query parameters to filter results:

status=active - Only return active tool identifiers
type=scm - Filter by tool type
usage=pipeline - Filter by usage context
enabledInToolRegistry=true - Only tools enabled in registry
search=github - Keyword search across tool identifiers
fields=identifier,name,active - Specify which fields to return

Use Cases

Pipeline Creation: Discover available step types before creating a pipeline
Validation: Verify a tool identifier is valid before using it
Documentation: Generate dynamic documentation of available tools
AI Agents: Programmatically explore available capabilities

Important Notes

Results are filtered by user roles and entitlements
Not all identifiers may have registered instances in your account

Required Access

Authentication: Bearer token is required
Permissions: All authenticated users can access this endpoint

Authorizations

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.

Query parameters

statusstringOptional

Filter by status (e.g., "active", "inactive"). Defaults to "active" if not specified.

Example: active

typestringOptional

Filter by tool type

Example: scm

usagestringOptional

Filter by usage context

Example: pipeline

enabledInToolRegistrybooleanOptional

Filter by tool registry enablement

Example: true

searchstringOptional

Keyword search filter

Example: github

fieldsstring[]Optional

Comma-separated list of fields to return. Defaults to "name,description,identifier,usageType" if not specified.

Example: identifier,name,active

Responses

200

Tool identifiers retrieved successfully

application/json

401

Unauthorized - Authentication failed

500

Internal Server Error

get

/api/v2/tools/identifiers

GET /api/v2/tools/identifiers HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "success",
  "data": [
    {
      "name": ".NET",
      "description": "Execute .NET scripts",
      "identifier": "dotnet",
      "usageType": "pipeline"
    }
  ],
  "metadata": {
    "count": 45
  }
}

Get Registered Tools

get

Returns a list of tools registered by the user, optionally filtered by tool identifier.

Each registered tool represents a configured instance of a tool type. For example, you might have multiple GitHub accounts registered, each with its own _id (toolConfigId).

AI Agent Workflow

This is typically the second endpoint to call when building a pipeline:

Get available identifiers from /api/v2/tools/identifiers
Call this endpoint with tool_identifier parameter for each tool you need
Extract the _id field from each tool (this becomes toolConfigId in step configuration)
Use the _id values when configuring pipeline steps

Example Workflow

// Step 1: Get registered GitHub tools
GET /api/v2/tools/registry?tool_identifier=github
Response: [{ "_id": "602242ea6fc729aa1de8608c", "name": "GitHub Main", ... }]

// Step 2: Get registered Snyk tools
GET /api/v2/tools/registry?tool_identifier=snyk
Response: [{ "_id": "63ce2159f40936002ebddc57", "name": "Snyk Scanner", ... }]

// Step 3: Use these IDs in pipeline step configuration
{
  "tool": {
    "tool_identifier": "SNYK",
    "configuration": {
      "toolConfigId": "63ce2159f40936002ebddc57",  // From step 2
      "gitToolId": "602242ea6fc729aa1de8608c",     // From step 1
      ...
    }
  }
}

Use Cases

Pipeline Configuration: Find the toolConfigId needed for pipeline step configuration
Tool Discovery: List all registered instances of a specific tool type
Validation: Verify a tool is registered before using it in a pipeline
Tool Selection: Present available tool options to users

Common Tool Identifiers

github, gitlab, bitbucket - SCM tools (use _id as gitToolId)
snyk, sonar - Security/Quality tools (use _id as toolConfigId)
jenkins - CI/CD tools (use _id as jenkinsToolId)
docker_push - Container registry (use _id as awsToolConfigId)
helm - Deployment tools

Performance Tips

Use tool_identifier parameter to filter results (faster than client-side filtering)
Use fields parameter to return only needed fields (_id, name, tool_identifier)

Required Access

Authentication: Bearer token is required
Permissions: User can only see tools they have access to

Authorizations

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.

Query parameters

tool_identifierstringOptional

Filter by tool identifier (e.g., github, snyk, sonar). When omitted, returns all registered tools.

Example: github

fieldsstringOptional

Comma-separated list of fields to return. Reduces response size when you only need specific fields.

Example: _id,name,tool_identifier

Responses

200

Registry tools retrieved successfully

application/json

401

Unauthorized - Authentication failed

500

Internal Server Error

get

/api/v2/tools/registry

GET /api/v2/tools/registry HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "success",
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "My GitHub Account",
      "tool_identifier": "github",
      "configuration": {}
    }
  ],
  "metadata": {
    "count": 5,
    "toolIdentifier": "github"
  }
}

Get SCM Repositories

post

Returns a list of repositories accessible from a registered SCM tool.

Use this endpoint to discover repositories for pipeline step configuration. The tool_id should be the _id of a registered SCM tool from /api/v2/tools/registry.

Supported Services

github - GitHub repositories
gitlab - GitLab repositories
bitbucket - Bitbucket repositories (requires workspace)
azure_devops - Azure DevOps repositories

Use Cases

Pipeline Configuration: Discover repositories to use in SCM steps
Repository Selection: Present a list of available repositories to users

Required Access

Authentication: Bearer token is required
Permissions: User must have access to the registered tool

Authorizations

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

tool_idstringRequired

MongoDB ObjectId of the registered SCM tool (from /api/v2/tools/registry)

Example: 507f1f77bcf86cd799439011

servicestring · enumRequired

SCM service type

Example: githubPossible values:

workspacestringOptional

Bitbucket workspace (required for Bitbucket)

Example: my-workspace

searchTermstringOptional

Filter repositories by name (partial match)

Example: my-api

pageSizeintegerOptional

Number of results per page (default 50)

Example: 100

currentPageintegerOptional

Page number for pagination (1-based)

Example: 1

Responses

200

Repositories retrieved successfully

application/json

400

Missing required fields

401

Unauthorized - Authentication failed

500

Internal Server Error

post

/api/v2/tools/scm/repositories

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

{
  "tool_id": "507f1f77bcf86cd799439011",
  "service": "github"
}

{
  "status": "success",
  "data": [
    {
      "name": "my-node-api",
      "full_name": "myorg/my-node-api",
      "url": "https://github.com/myorg/my-node-api"
    }
  ],
  "metadata": {
    "count": 25,
    "service": "github"
  }
}

Get SCM Branches

post

Returns a list of branches for a specific repository in a registered SCM tool.

Use this endpoint to discover branches for pipeline step configuration. First, get the repository from /api/v2/tools/scm/repositories, then use this endpoint to list available branches.

Use Cases

Pipeline Configuration: Discover branches to use in SCM steps
Branch Selection: Present a list of available branches to users

Required Access

Authentication: Bearer token is required
Permissions: User must have access to the registered tool

Authorizations

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

tool_idstringRequired

MongoDB ObjectId of the registered SCM tool

Example: 507f1f77bcf86cd799439011

servicestring · enumRequired

SCM service type

Example: githubPossible values:

repositorystringRequired

Repository identifier (e.g., owner/repo or repo ID)

Example: myorg/my-node-api

workspacestringOptional

Bitbucket workspace (required for Bitbucket)

Example: my-workspace

searchTermstringOptional

Filter branches by name (partial match)

Example: feature

Responses

200

Branches retrieved successfully

application/json

400

Missing required fields

401

Unauthorized - Authentication failed

500

Internal Server Error

post

/api/v2/tools/scm/branches

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

{
  "tool_id": "507f1f77bcf86cd799439011",
  "service": "github",
  "repository": "myorg/my-node-api"
}

{
  "status": "success",
  "data": [
    {
      "name": "main",
      "default": true
    }
  ],
  "metadata": {
    "count": 5,
    "repository": "myorg/my-node-api"
  }
}

PreviousTool Registry NextUser Management

Last updated 3 days ago

Good afternoon

hashtagGet Available Tool Identifiers

hashtagAI Agent Workflow

hashtagEntitlement Filtering

hashtagQuery Parameters

hashtagUse Cases

hashtagImportant Notes

hashtagRequired Access

hashtagGet Registered Tools

hashtagAI Agent Workflow

hashtagExample Workflow

hashtagUse Cases

hashtagCommon Tool Identifiers

hashtagPerformance Tips

hashtagRequired Access

hashtagGet SCM Repositories

hashtagSupported Services

hashtagUse Cases

hashtagRequired Access

hashtagGet SCM Branches

hashtagUse Cases

hashtagRequired Access

Get Available Tool Identifiers

AI Agent Workflow

Entitlement Filtering

Query Parameters

Use Cases

Important Notes

Required Access

Get Registered Tools

AI Agent Workflow

Example Workflow

Use Cases

Common Tool Identifiers

Performance Tips

Required Access

Get SCM Repositories

Supported Services

Use Cases

Required Access

Get SCM Branches

Use Cases

Required Access