Humanitec Agents API
An object containing the details of an Agent.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/humanitec-agents-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Humanitec Agents API
version: 0.28.24
description: '# Introduction
The *Humanitec API* allows you to automate and integrate Humanitec into your developer and operational workflows.
The API is a REST based API. It is based around a set of concepts:
* Core
* External Resources
* Sets and Deltas
## Authentication
Almost all requests made to the Humanitec API require Authentication. See our [Developer Docs on API Authentication](https://developer.humanitec.com/platform-orchestrator/reference/api-references/#authentication) for instructions.
## Content Types
The Humanitec API, unless explicitly specified, only accepts content types of `application/json` and will always return valid `application/json` or an empty response.
## Response Codes
### Success
Any response code in the `2xx` range should be regarded as success.
| **Code** | **Meaning** |
|----------|-------------------------------------|
| `200` | Success |
| `201` | Success, a new resource was created |
| `204` | Success, but no content in response |
_Note: We plan to simplify the interface by replacing 201 with 200 status codes._
### Failure
Any response code in the `4xx` range should be regarded as an error that can be rectified by the client. `5xx` error codes indicate errors that cannot be corrected by the client.
| **Code** | **Meaning** |
|----------|-----------------------------------------------------------------------------------------------------------------------|
| `400` | General error. (Body will contain details) |
| `401` | Attempt to access protected resource without `Authorization` Header. |
| `403` | The `Bearer` or `JWT` does not grant access to the requested resource. |
| `404` | Resource not found. |
| `405` | Method not allowed |
| `409` | Conflict. Usually indicated a resource with that ID already exists. |
| `422` | Unprocessable Entity. The body was not valid JSON, was empty or contained an object different from what was expected. |
| `429` | Too many requests - request rate limit has been reached. |
| `500` | Internal Error. If it occurs repeatedly, contact support. |
'
contact:
name: Humanitec Support
email: support@humanitec.com
x-logo:
url: humanitec-logo.png
altText: Humanitec logo
servers:
- url: https://api.humanitec.io/
tags:
- name: Agents
x-displayName: Agents
description: 'An object containing the details of an Agent.
<SchemaDefinition schemaRef="#/components/schemas/Agent" />
'
paths:
/orgs/{orgId}/agents:
post:
tags:
- Agents
operationId: createAgent
summary: Register a new Agent under an Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCreateBody'
responses:
'200':
description: Agent registered.
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'400':
$ref: '#/components/responses/400BadRequest'
'409':
$ref: '#/components/responses/409Conflict'
get:
tags:
- Agents
operationId: listAgents
summary: List all the agents in an Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/fingerprintQueryParam'
responses:
'200':
description: Successful list response.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Agent'
/orgs/{orgId}/agents/{agentId}:
delete:
tags:
- Agents
operationId: deleteAgent
summary: Delete an Agent (and its keys) stored under an Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/agentIdPathParam'
responses:
'204':
description: Agent successfully deleted.
'404':
$ref: '#/components/responses/404NotFound'
patch:
tags:
- Agents
operationId: patchAgent
summary: Update the description of an Agent.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/agentIdPathParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentPatchBody'
responses:
'200':
description: Agent updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'400':
$ref: '#/components/responses/400BadRequest'
'404':
$ref: '#/components/responses/404NotFound'
/orgs/{orgId}/agents/{agentId}/keys:
get:
tags:
- Agents
operationId: listKeysInAgent
summary: List all the keys registered under an Agent in an Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/agentIdPathParam'
responses:
'200':
description: Successful list response.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Key'
'404':
$ref: '#/components/responses/404NotFound'
post:
tags:
- Agents
operationId: createKey
summary: Register a new Key under an Agent in an Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/agentIdPathParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/KeyCreateBody'
responses:
'200':
description: Successful list response.
content:
application/json:
schema:
$ref: '#/components/schemas/Key'
'400':
$ref: '#/components/responses/400BadRequest'
'404':
$ref: '#/components/responses/404NotFound'
'409':
$ref: '#/components/responses/409Conflict'
/orgs/{orgId}/agents/{agentId}/keys/{fingerprint}:
delete:
tags:
- Agents
operationId: deleteKeyInAgent
summary: Delete a key registered under a Agent.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/agentIdPathParam'
- $ref: '#/components/parameters/fingerprintPathParam'
responses:
'204':
description: Key successfully deleted.
'404':
$ref: '#/components/responses/404NotFound'
components:
responses:
409Conflict:
description: 'The request itself is valid however it could not be applied based on the current state of the resource.
More detail can be found in the error body.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
400BadRequest:
description: The request was invalid. More detail can be found in the error body.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
404NotFound:
description: Either the resource or a related resource could not be found. More detail can be found in the error body.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
schemas:
KeyCreateBody:
properties:
public_key:
type: string
description: A pcks8 RSA public key PEM encoded (as the ones produced by openssl), whose module length is greater or equal than 4096 bits.
example: '-----BEGIN PUBLIC KEY-----
...-----END PUBLIC KEY-----'
required:
- public_key
HumanitecErrorResponse:
description: HumanitecError represents a standard Humanitec Error
properties:
details:
additionalProperties: true
type: object
description: (Optional) Additional information is enclosed here.
error:
type: string
example: API-000
description: A short code to help with error identification.
message:
type: string
example: Could not validate token
description: A Human readable message about the error.
required:
- error
- message
type: object
example:
error: API-000
message: Could not validate token.
Key:
description: An object containing the details of a Key.
properties:
fingerprint:
type: string
description: The Key fingerprint (sha256 hash of the DER representation of the key).
example: 9be36d7e31323a00e88facdd50843accd95ddbcffaefea28e49c28c08399417d
public_key:
type: string
description: A pcks8 RSA ublic key PEM encoded.
example: '-----BEGIN PUBLIC KEY-----
...-----END PUBLIC KEY-----'
created_at:
type: string
example: '2020-06-22T09:37:23.523Z'
format: date-time
description: Time of the Key being registered.
created_by:
type: string
description: User ID of user that added the Key.
example: 00000000-0000-0000-0000-000000000000
expired_at:
type: string
example: '2022-06-22T09:37:23.523Z'
format: date-time
description: Time when the Key should be replaced (2 years after its creation).
is_authorized:
type: boolean
description: If this key has been authorized to be used to validate requests coming from an Agent.
example: true
required:
- fingerprint
- public_key
- created_at
- created_by
- expired_at
- is_authorized
AgentPatchBody:
description: An object containing data to update the description field of an Agent.
properties:
description:
type: string
description: A description to show future users. It can be empty.
example: One of my agents.
required:
- description
Agent:
description: An object containing the details of an Agent.
properties:
id:
type: string
description: The Agent id.
example: agent-id
description:
type: string
description: A description to show future users. It can be empty.
example: One of my agents.
created_at:
type: string
example: '2020-06-22T09:37:23.523Z'
format: date-time
description: Time of the Agent being registered.
created_by:
type: string
description: User ID of user that added the Agent.
example: 00000000-0000-0000-0000-000000000000
required:
- id
- created_at
- created_by
AgentCreateBody:
description: An object containing data needed to register an Agent.
properties:
id:
type: string
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
description: The Agent id. It can't be empty and should contain only url safe characters.
example: agent-id
public_key:
type: string
description: A pcks8 RSA public key PEM encoded (as the ones produced by openssl), whose module length is greater or equal than 4096 bits.
example: '-----BEGIN PUBLIC KEY-----
...-----END PUBLIC KEY-----'
description:
type: string
description: An optional description to show future users.
example: One of my agents.
required:
- id
- public_key
parameters:
agentIdPathParam:
name: agentId
in: path
description: The Agent id.
example: my-agent
required: true
schema:
type: string
fingerprintPathParam:
name: fingerprint
in: path
description: The Key fingerprint (hexadecimal representation of sha256 hash of the DER representation of the key).
example: 9be36d7e31323a00e88facdd50843accd95ddbcffaefea28e49c28c08399417d
required: true
schema:
type: string
orgIdPathParam:
name: orgId
in: path
description: The Organization ID
example: sample-org
required: true
schema:
type: string
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
maxLength: 50
fingerprintQueryParam:
name: fingerprint
in: query
description: The Key fingerprint (hexadecimal representation of sha256 hash of the DER representation of the key).
example: 9be36d7e31323a00e88facdd50843accd95ddbcffaefea28e49c28c08399417d
schema:
type: string
externalDocs:
description: Find out more about how to use Humanitec in your every-day development work.
url: https://developer.humanitec.com/
x-tagGroups:
- name: Core
tags:
- Agents
- Application
- Artefact
- ArtefactVersion
- AuditLogs
- Logs
- Deployment
- EnvironmentType
- Environment
- Image
- PublicKeys
- Organization
- Registry
- RuntimeInfo
- SecretStore
- Value
- ValueSetVersion
- name: App Configuration
tags:
- Delta
- Set
- WorkloadProfile
- name: Resources
tags:
- ActiveResource
- DriverDefinition
- MatchingCriteria
- ResourceDefinition
- ResourceDefinitionVersion
- ResourceProvision
- AccountType
- ResourceAccount
- ResourceType
- ResourceClass
- name: Automation
tags:
- AutomationRule
- Event
- Pipelines
- PipelineRuns
- PipelineApprovals
- name: Users
tags:
- UserProfile
- UserRole
- Group
- TokenInfo