API docs by Redocly

HUMAN API (1.0.0)

Download OpenAPI specification:

HUMAN platform API

Command Plane — Orgs

Organization management: create, configure, and manage CP orgs

Command Plane — Agents

Internal agent management: list, pause, resume, and set autonomy overrides

Command Plane — Marketplace

Marketplace: browse, submit, install, review, and manage assets

Command Plane — Audit

Audit spine: provenance timeline, AI summaries, retention policies

Command Plane — Diagnostics

System diagnostics: run checks, view history, manage incidents

Command Plane — Incidents

Incident management: view, investigate, and resolve platform incidents

Command Plane — Escalations

Human-in-the-loop escalation queue: list and respond to approval requests

Respond to an escalation

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
decision
required
string
Enum: "approve" "approved_with_modifications" "reject" "request_changes"
notes
string
modifications
string

Responses

Request samples

Content type
application/json
{
  • "decision": "approve",
  • "notes": "string",
  • "modifications": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Command Plane — Devices

Device and topology management: enroll devices, map edges

Command Plane — Cloud Admin

Internal HUMΛN Cloud Admin plane (cloud:admin:global required)

Cloud admin overview

Requires cloud:admin:global scope and DEPLOYMENT_MODE=cloud.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Operations

Check the platform's health status

The health endpoint provides a window into the current operational status of the HUMAN platform. By revealing the connectivity state and version details, it ensures transparency and builds trust with users, crucial for maintaining a robust and reliable Human-AI orchestration environment.

Responses

Response samples

Content type
application/json

Response indicating a fully operational platform with database connectivity.

{
  • "status": "ok",
  • "database": "connected",
  • "version": "1.2.3",
  • "commit": "abc123def",
  • "timestamp": "2023-10-02T12:34:56Z"
}

Check platform readiness and component health

The GET /ready endpoint provides a vital snapshot of the HUMAN platform's operational status, ensuring that both the database and Redis components are functioning correctly. This health check empowers system administrators to maintain a seamless orchestration of Human-AI tasks by proactively identifying and addressing potential service disruptions.

Responses

Response samples

Content type
application/json

The system is fully operational, with all components connected.

{
  • "ready": true,
  • "database": "connected",
  • "redis": "connected",
  • "timestamp": "2023-03-15T12:45:30.000Z"
}

Pause an agent's task acceptance

In the dynamic world of Human-AI orchestration, sometimes an agent needs a breather. This endpoint halts an agent's ability to accept new tasks, ensuring that our orchestration remains finely tuned and agile. Whether it's for routine maintenance or strategic planning, pausing gives you control over the flow of operations.

Request Body schema: application/json
required
reason
string

Optional explanation for pausing the agent

Responses

Request samples

Content type
application/json

Pausing the agent for routine system maintenance

{
  • "reason": "Scheduled maintenance"
}

Response samples

Content type
application/json
{
  • "agent": {
    }
}

Resume a paused agent's operations

In the dynamic world of Human-AI collaboration, agents sometimes need to pause. This endpoint breathes life back into a paused agent, restoring its active status and enabling it to perform its designated tasks. It's a critical function for maintaining seamless operations and ensuring that your digital workforce is always at the ready.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Monitoring

Check the platform's health status

The health endpoint provides a window into the current operational status of the HUMAN platform. By revealing the connectivity state and version details, it ensures transparency and builds trust with users, crucial for maintaining a robust and reliable Human-AI orchestration environment.

Responses

Response samples

Content type
application/json

Response indicating a fully operational platform with database connectivity.

{
  • "status": "ok",
  • "database": "connected",
  • "version": "1.2.3",
  • "commit": "abc123def",
  • "timestamp": "2023-10-02T12:34:56Z"
}

Poll execution status asynchronously

Retrieve the current status of an execution task. This endpoint enables clients to track the progress of tasks managed by HUMAN's orchestration layer, ensuring transparent and reliable updates without blocking operations.

Responses

Response samples

Content type
application/json
Example
{
  • "execution_id": "exec_abc123",
  • "status": "processing",
  • "created_at": "2025-11-25T10:30:00.000Z",
  • "updated_at": "2025-11-25T10:30:05.000Z",
  • "started_at": "2025-11-25T10:30:01.000Z",
  • "message": "Execution is currently being processed"
}

Create a new HumanOS watch

The endpoint empowers organizations to create a monitoring watch on various HumanOS entities, ensuring vigilant oversight and preemptive action. By tracking events, sources, or patterns, it provides a strategic advantage in maintaining operational integrity and safety.

Request Body schema: application/json
required
target_ref
required
string

The reference to the target entity or pattern to watch.

watch_kind
required
string
Enum: "entity" "source" "event_type" "pattern"

The kind of watch to establish, dictating the monitoring scope.

owner_ref
string

Identifier for the owner of the watch, defaulting to the context's delegation if not provided.

scope
string

Scope of the watch, typically 'org' for organization-wide.

schedule
object

JSON object representing the watch's scheduling parameters.

Responses

Request samples

Content type
application/json

Creating a watch for monitoring a specific event type within an organization.

{
  • "target_ref": "event_type:invoice_processed",
  • "watch_kind": "event_type",
  • "owner_ref": "did:example:123456789abcdefghi",
  • "scope": "org",
  • "schedule": {
    }
}

Response samples

Content type
application/json
null

Retrieve active HumanOS watch entries

In the HumanOS, watches are guardians of the orchestration protocol, monitoring vast landscapes of tasks and capabilities. This endpoint reveals a curated list of these sentinels, filtered by your organizational identity, ensuring only those you are permitted to view are displayed. The power of delegation and oversight is at your fingertips, enabling you to manage the intricate web of tasks with precision.

Responses

Response samples

Content type
application/json

Retrieve the list of watches currently monitored by Acme Corp, showing task oversight in action.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Identity

Resolve a DID for the HUMAN platform

Dive into the world of decentralized identities with the HUMAN platform's DID resolution endpoint. This service allows you to retrieve a well-defined DID Document, crucial for establishing verifiable digital identities. It's a gateway to ensuring trust and authenticity in a decentralized ecosystem, enabling seamless human-AI interaction.

Responses

Response samples

Content type
application/json

A DID Document for the Acme Corporation's API service

{}

Create a delegation token for access control

In the intricate dance of human and AI collaboration, the Delegation Token is your backstage pass. It empowers entities to act on behalf of others, streamlining operations without sacrificing security. This endpoint creates a token, ensuring trusted interactions across the HUMAN platform.

Request Body schema: application/json
required
delegate
required
string

The DID of the delegate requesting access.

capabilities
required
Array of strings
expiresIn
integer

Time in seconds until the token expires.

Responses

Request samples

Content type
application/json

This example shows how to delegate invoice processing capabilities to an AI agent within the 'acme' organization.

{
  • "delegate": "did:human:agent-12345",
  • "capabilities": [
    ],
  • "expiresIn": 3600
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "expiresAt": "2023-10-15T10:00:00Z"
}

Confirm device authorization with user code

In the world of distributed identity, confirming a device's authorization is crucial for seamless access. This endpoint allows a device to authenticate using a unique user code, ensuring that only trusted devices can operate within the HUMAN ecosystem. It's a vital step in maintaining the security and integrity of digital identities.

Request Body schema: application/json
required
user_code
required
string

A unique code to verify the device, formatted as XXXX-XXXX.

Responses

Request samples

Content type
application/json

A typical request with a correctly formatted user code.

{
  • "user_code": "WDJB-MJHT"
}

Response samples

Content type
application/json
{
  • "user_code": "WDJB-MJHT",
  • "status": "approved",
  • "subject_did": "did:example:123456789abcdefghi"
}

Retrieve details of a specific agent

Discover the capabilities and identity of a specific agent within the HUMAN ecosystem. This endpoint allows you to access detailed information about an agent, tracked through the HUMAN Passport and Capability Graph, to understand its roles and functions. Uncover how agents are orchestrated to perform tasks safely and transparently.

Request Body schema: application/json
required
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
null

Retrieve organizations for a passport

Discover the organizations where your cryptographic identity, or Passport, is a recognized member. This endpoint allows you to navigate through your affiliations, providing a seamless connection to your roles and responsibilities across the HUMAN network.

Responses

Response samples

Content type
application/json

A user fetches their affiliated organizations.

{
  • "data": [
    ],
  • "limit": 2,
  • "nextCursor": "eyJjcmVhdGVkX2F0IjoiMjAyMy0wOC0yMlQwODoyMTozM1oifQ=="
}

Retrieve Grants for Authenticated User

Explore the intricate web of permissions with the HUMAN platform by listing all grants where you are the granter. This endpoint unifies both delegation and capability grants into a single view, empowering you to understand and manage the permissions you have bestowed.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "nextCursor": "cursor_string"
}

Revoke a specific passport grant

In the intricate dance of digital identity, sometimes you need to call back a partner. This endpoint allows a user to revoke a specific grant, immediately updating its status. It ensures that only the rightful owner of the digital identity can perform such a critical action, maintaining trust in our distributed ecosystem.

Request Body schema: application/json
required
reason
string

Reason for revocation, providing context for the action

Responses

Request samples

Content type
application/json

Revoking a grant with an explanation

{
  • "reason": "No longer needed for current project"
}

Response samples

Content type
application/json
{
  • "grant_id": "grant_12345",
  • "grant_type": "delegation",
  • "status": "revoked",
  • "revoked_at": "2023-10-12T08:45:30Z",
  • "revoked_by": "did:example:123456789abcdefghi",
  • "reason": "No longer required"
}

Unpause a paused delegation grant

In the symphony of human and AI collaboration, sometimes we need to hit pause. But when you're ready to resume the dance, this endpoint lets you seamlessly transition a paused delegation grant back to its active state. It's your cue to continue orchestrating magic.

Responses

Response samples

Content type
application/json

Successfully unpausing a delegation grant for user interaction to continue.

{
  • "delegation_id": "grant_12345",
  • "status": "active"
}

Create a new service account

This endpoint empowers organizations to create service accounts linked to their digital identity, enhancing automated interactions with HUMAN's ecosystem. Service accounts facilitate automated access to resources, allowing seamless integration while maintaining security through scoped permissions and IP allowlists.

Request Body schema: application/json
required
name
required
string

A descriptive name for the service account.

description
string

Optional detailed information about the service account's purpose.

scopes
required
Array of strings

An array of capability URIs defining the service account's permissions.

ip_allowlist
Array of strings <ipv4> [ items <ipv4 > ]

A list of IP addresses allowed to use this service account.

owner_passport_did
string

The DID of the owner passport, starting with 'did:human:'.

Responses

Request samples

Content type
application/json

This example demonstrates setting up a service account for 'acme' organization to automate invoice processing.

{
  • "name": "Invoice Processor",
  • "description": "Handles automated invoice processing tasks.",
  • "scopes": [
    ],
  • "ip_allowlist": [
    ],
  • "owner_passport_did": "did:human:org:acme"
}

Response samples

Content type
application/json

A successful response after creating a service account for 'acme'.

{
  • "service_account_id": "hsa12345",
  • "api_key": "HSK_live_4bGZ2k...",
  • "name": "Invoice Processor",
  • "scopes": [
    ],
  • "ip_allowlist": [
    ],
  • "created_at": "2023-10-01T08:00:00Z"
}

Verify the authenticity of a Passport credential

Dive into the heart of identity verification with this endpoint, where credentials are scrutinized to ensure trustworthiness. In a world where digital identities are pivotal, knowing the truth behind a credential is paramount. This service verifies the integrity and validity of a Passport credential, giving organizations the confidence they need in their digital interactions.

Request Body schema: application/json
required
One of
credential_id
required
string

The unique identifier for the credential

Responses

Request samples

Content type
application/json

An example of verifying a credential using the modern field name

{
  • "credential_id": "cred-12345"
}

Response samples

Content type
application/json
null

Retrieve Verified Credentials for Passport

Delve into the rich tapestry of your digital identity by retrieving your verified credentials. This endpoint empowers you to securely access and manage the credentials tied to your Passport, ensuring that only you hold the key to your identity's narrative.

Responses

Response samples

Content type
application/json

Shows a successful retrieval of credentials for a user's Passport.

{
  • "credentials": [
    ],
  • "cursor": "opaque-cursor-string",
  • "hasMore": false,
  • "total": 1
}

Create Verifiable Credential for Human Passport

This endpoint empowers organizations and agents to issue verifiable credentials tied to a human's digital identity. By securely managing these credentials, organizations can assert skills or qualifications that are cryptographically verifiable, enhancing trust in digital interactions.

Request Body schema: application/json
required
subject_did
required
string

The DID of the human subject receiving the credential.

issuer_did
required
string

The DID of the issuer, which must be an org or agent.

type
required
Array of strings

The type(s) of credential being issued.

claims
required
object

A JSON object representing claims associated with the credential.

expiration_date
string <date-time>

The optional expiration date for the credential in ISO 8601 format.

Responses

Request samples

Content type
application/json

Demonstrates issuing a credential asserting a skill proficiency.

{
  • "subject_did": "did:human:123456789abcdefghi",
  • "issuer_did": "did:org:acme",
  • "type": [
    ],
  • "claims": {
    },
  • "expiration_date": "2025-12-31T23:59:59Z"
}

Response samples

Content type
application/json
null

Register device options for a passport

In the HUMAN ecosystem, binding devices to digital identities is crucial for secure interactions. This endpoint generates registration options, allowing a device to be securely linked to a human passport. It ensures that only the rightful owner of the passport can initiate this process, preserving the integrity of the system.

Responses

Response samples

Content type
application/json

Alice from Acme Corp is registering a new device.

{
  • "registration_id": "reg-123456",
  • "options": {
    }
}

Revoke a Device from a Passport

In the complex dance of digital identity, sometimes a device needs to gracefully exit the stage. This endpoint allows you to revoke a device from a user's Passport, ensuring that access is controlled and secure. Whether it's a lost device or a change in access policy, this operation keeps your digital space safe.

Request Body schema: application/json
required
One of
required
object
revocation_reason
string
request_id
string

Responses

Request samples

Content type
application/json

Revoking a device with a reason and request ID

{
  • "authorization": {
    },
  • "revocation_reason": "Device lost",
  • "request_id": "req-789"
}

Response samples

Content type
application/json
{
  • "device_id": "device-abc",
  • "revoked_at": "2023-10-05T14:48:00.000Z",
  • "status": "revoked",
  • "revocation_event_id": "rev-event-123"
}

Retrieve a user’s cryptographic identity

Delve into the realm of digital authenticity by fetching a user’s cryptographic identity from the HUMAN ecosystem. This endpoint allows authenticated users to explore their unique digital footprint, encapsulating their identity and associated devices, ensuring a seamless blend of privacy and transparency.

Responses

Response samples

Content type
application/json

Retrieving John's digital passport details, including active devices and credential counts.

{
  • "did": "did:human:123456789abcdef",
  • "display_name": "John Doe",
  • "person_type": "individual",
  • "created_at": "2023-01-15T12:34:56Z",
  • "is_active": true,
  • "credential_count": 3,
  • "devices": [
    ]
}

Request Passport Disclosure

Initiate a request for specific identity disclosures tied to a human DID. This endpoint empowers applications to verify identity attributes while maintaining control over privacy and consent. It's a gateway to a world where digital trust is built on human identity, not just numbers.

Request Body schema: application/json
required
subject_did
required
string

The DID of the human whose attributes are being requested. Must start with 'did:human:'.

requested_attributes
required
Array of strings

Array of attribute names to disclose.

purpose
string

The purpose of the disclosure request.

expires_in
integer

The time in seconds until the request expires, between 60 and 604800 (7 days).

Responses

Request samples

Content type
application/json

A request to obtain the email and phone number of a user for account verification purposes.

{
  • "subject_did": "did:human:123456789abcdefghi",
  • "requested_attributes": [
    ],
  • "purpose": "Account verification",
  • "expires_in": 3600
}

Response samples

Content type
application/json
{}

Revoke a Passport Consent

When trust is no longer warranted, revoke a consent tied to a Passport. This endpoint ensures control over shared data and maintains user sovereignty.

Request Body schema: application/json
required
One of
revocation_reason
required
string

The reason for revocation.

Responses

Request samples

Content type
application/json

Shows how to revoke consent when data policy updates require it.

{
  • "revocation_reason": "Data policy changes require consent review."
}

Response samples

Content type
application/json
{
  • "consent_id": "consent-12345",
  • "status": "revoked",
  • "revoked_at": "2023-10-21T14:48:00.000Z"
}

Retrieve organization's slug if claimed

Discover the unique and memorable slug associated with an organization, revealing its digital identity on the HUMAN platform. This endpoint addresses the need for distinct identification, ensuring seamless interaction and recognition in a distributed, AI-driven ecosystem.

Responses

Response samples

Content type
application/json

Fetching the slug for 'acme-corp'.

{
  • "slug": "acme-corp",
  • "org_did": "did:human:example123",
  • "display_name": "Acme Corporation",
  • "claimed_at": "2023-10-05T14:48:00.000Z"
}

Create a new credential attestation

Forge a verifiable link between an organization and a subject through cryptographic identity. This endpoint empowers organizations to attest to credentials, securely embedding trust into decentralized interactions. By weaving human intent with machine precision, it strengthens the backbone of the HUMAN network.

Request Body schema: application/json
required
subject_did
required
string

Decentralized Identifier (DID) of the subject receiving the credential.

object

Additional attributes to include in the attestation payload.

Responses

Request samples

Content type
application/json

Attesting a credential for Alice under the organization 'acme'.

{
  • "subject_did": "did:example:alice",
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "attestation_id": "cp_att_cred_12345",
  • "attestation_kind": "credential",
  • "subject_did": "did:example:alice",
  • "created_at": "2023-10-22T14:48:00Z"
}

Retrieve Passport Jurisdiction Proofs

Unravel the cryptographic tapestry of identity by accessing jurisdiction-specific proofs associated with a Passport DID. This endpoint empowers organizations to verify identity assertions across borders, ensuring trust and compliance in human-AI orchestration.

Responses

Response samples

Content type
application/json

This example shows proofs retrieved for ACME Corp under the jurisdiction of 'US'.

{
  • "jurisdiction": "US",
  • "passport_did": "did:human:123456789abcdefghi",
  • "proofs": [
    ]
}

Retrieve organization details by DID

Delve into the heart of HUMAN's orchestration by fetching the details of an organization using its Decentralized Identifier (DID). This endpoint empowers you to access essential data that defines an organization’s identity within the HUMAN network, ensuring seamless integration and interaction.

Responses

Response samples

Content type
application/json
{
  • "orgDid": "did:human:123456789abcdefghi",
  • "name": "Acme Corporation",
  • "createdAt": "2023-10-01T12:34:56Z"
}

Retrieve detailed agent information by ID

Unlock the power of your HUMAN agents by retrieving detailed information using their unique identifiers. Whether you're exploring agents by their cryptographic DIDs or their organizational identifiers, this endpoint provides a comprehensive view of an agent's identity, capabilities, and operational context.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Create a new API signing key

This endpoint allows you to create a named Human API signing key linked to a specific passport. API signing keys are essential for securing session-based operations, ensuring that all interactions are traceable to a verified identity. This feature provides an additional layer of security and traceability within the HUMAN ecosystem.

Request Body schema: application/json
required
label
required
string

A human-readable label for the API signing key. Maximum 128 characters.

Responses

Request samples

Content type
application/json

Creating a signing key for the 'acme-invoice-processing' application.

{
  • "label": "acme-invoice-processing-key"
}

Response samples

Content type
application/json

Response after successfully creating a signing key for 'acme-invoice-processing'.

{
  • "key_id": "hask_123456789",
  • "public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAn...",
  • "fingerprint": "3F:9F:6B:2D:EE:4A:08:3B:4B:54:C6:03:9C:2D:7C:1D",
  • "label": "acme-invoice-processing-key",
  • "created_at": "2023-10-21T14:32:28Z"
}

Retrieve active API signing keys

Discover the active cryptographic keys that secure communications with HUMAN API. This endpoint is vital for ensuring the integrity and authenticity of interactions by listing the valid keys tied to a Passport, empowering trusted integration.

Responses

Response samples

Content type
application/json

Shows a Passport with multiple active API signing keys and pagination.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Retrieve specific API signing key metadata

Explore the cryptographic essence of your identity with the Passport's API signing key metadata. This endpoint unveils the details of a specific active key, enabling secure and traceable interactions within the HUMAN network. Discover when it was created, its fingerprint, and more, as you navigate the digital realm with confidence.

Responses

Response samples

Content type
application/json
{
  • "key_id": "key_12345",
  • "label": "Invoice Processing Key",
  • "fingerprint": "abc123base64encodedfingerprint==",
  • "created_at": "2023-10-01T14:30:00Z",
  • "last_used_at": "2023-10-15T09:00:00Z"
}

Delegate Capabilities with JWT

This endpoint allows the creation of a delegation JWT from an issuer's passport, enabling secure sharing of capabilities. By delegating specific roles and permissions, organizations and agents can orchestrate tasks efficiently while maintaining control over access and expiry.

Request Body schema: application/json
required
toPassportId
required
string

The DID of the passport receiving the delegation.

scope
required
Array of strings

Array of capability IDs to be delegated.

expiresAt
string <date-time>

Optional expiration date for the delegation.

resources
Array of strings

Optional list of resource identifiers.

object

Optional constraints for the delegation.

signing_key_id
string

Optional ID for Human API signing key, required for human issuers.

Responses

Request samples

Content type
application/json

Delegating invoice processing capabilities to an agent in the 'acme' organization.

{
  • "toPassportId": "did:human:1234abc",
  • "scope": [
    ],
  • "expiresAt": "2024-12-31T23:59:59Z",
  • "resources": [
    ],
  • "conditions": {
    }
}

Response samples

Content type
application/json
{
  • "delegation_id": "dtok_5678def",
  • "from_passport_id": "did:human:5678def",
  • "to_passport_id": "did:human:1234abc",
  • "scope": [
    ],
  • "resources": [
    ],
  • "status": "active",
  • "conditions": {
    },
  • "expires_at": "2024-12-31T23:59:59Z",
  • "created_at": "2023-10-01T12:00:00Z",
  • "delegation_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Generate WebAuthn Recovery Options

In the labyrinth of digital identity, recovery is paramount. This endpoint crafts WebAuthn recovery options for a Human passport, ensuring you never lose access to what's rightfully yours. Designed for only the most human of identities, it locks out the non-human pretenders.

Responses

Response samples

Content type
application/json

A Human passport successfully retrieves WebAuthn recovery options.

{
  • "challenge_id": "abc123xyz",
  • "options": {
    }
}

Rotate WebAuthn Keys for Passport

Securely rotate WebAuthn keys for a human passport, ensuring cryptographic integrity. This endpoint facilitates the transition to new keys by generating necessary WebAuthn options, enhancing the security and trust in identity management.

Responses

Response samples

Content type
application/json

Example of a successful response with WebAuthn registration options.

{
  • "registration_id": "reg_123456789",
  • "options": {
    }
}

Register a Human Passport for Discovery

Embark on the journey of identity verification by registering your cryptographic Passport with HUMAN. This endpoint ensures the integrity of the self-signed proof from your device-rooted Passport, making it discoverable within the HUMAN ecosystem.

Request Body schema: application/json
required
passportData
required
string

Base64-encoded passport data containing the cryptographic proof.

Responses

Request samples

Content type
application/json

Registering a new passport for the Acme organization.

{
  • "passportData": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
{
  • "message": "Passport registered successfully.",
  • "passportId": "acme-passport-12345"
}

Retrieve Visible Organization Passports

Explore the world of cryptographic identities with the HUMAN platform's Passport retrieval. This endpoint unveils the passports of organizations where you are a recognized founder or where your organization is a delegation grantor, providing a window into the interconnected web of legal entities. Experience seamless navigation through the Capability Graph as you harness the power of AI to track skills and ensure task safety with HumanOS.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Retrieve detailed passport information

This endpoint unveils the cryptographic identity encapsulated within a passport, serving the dual purpose of identity verification and skill tracking in the HUMAN ecosystem. It caters to diverse identities, from humans to organizations and agents, each with its own unique narrative, ensuring a seamless interplay between identity and capability.

Responses

Response samples

Content type
application/json

Retrieving a human's passport with detailed identity verification.

{
  • "passport_id": "did:human:123456789abcdefghi",
  • "did": "did:human:123456789abcdefghi",
  • "type": "Human",
  • "name": "Jane Doe",
  • "public_key": "abcdef1234567890",
  • "did_document": {
    },
  • "created_at": "2023-10-05T12:34:56Z",
  • "updated_at": "2023-10-10T15:00:00Z",
  • "vault_endpoint": "https://vault.human-protocol.org/v1/jane",
  • "vault_kdf_salt": "s0m3s4lt",
  • "avatar_url": "https://avatars.human-protocol.org/jane.jpg",
  • "preferred_language": "en"
}

Modify User Passport Information

Empower users to customize their digital identity by updating fields like avatar and display name. This fosters a personalized experience while maintaining strict security protocols, ensuring only the rightful owner can make changes.

Request Body schema: application/json
required
avatar_url
string or null <uri>

URL of the user's avatar image

display_name
string

The name displayed on the user's profile

email
string or null <email>

User's contact email

preferred_language
string or null^[a-z]{2,3}(-[A-Z]{2,4})?$

Preferred language in BCP-47 format

Responses

Request samples

Content type
application/json

An update where the user changes their avatar and display name

{}

Response samples

Content type
application/json
{
  • "passport_id": "did:human:abc123",
  • "display_name": "Jane Doe",
  • "avatar_url": "https://example.com/images/avatar.png",
  • "email": "jane.doe@example.com",
  • "preferred_language": "en",
  • "updated_at": "2023-10-01T12:00:00Z"
}

Retrieve active passport cryptographic keys

Unlock the potential of secure identity verification by retrieving the active cryptographic keys associated with a specific passport. This endpoint ensures the integrity and authenticity of communications on the HUMAN platform, empowering both humans and AI to interact with confidence.

Responses

Response samples

Content type
application/json

An example response showing keys for Acme Corporation's cryptographic passport.

{
  • "keys": [
    ]
}

Rotate Passport Cryptographic Keys

In the HUMAN ecosystem, maintaining the security of your cryptographic identity is paramount. This endpoint allows passport holders to rotate their keys, ensuring that their digital identity remains secure and up-to-date. By rotating keys, users can refresh their cryptographic credentials, which is essential for maintaining trust and security in their interactions on the platform.

Request Body schema: application/json
required
One of
webauthn_auth
required
object
webauthn_attest
required
object
purposes
Array of strings
Items Enum: "auth" "attest"

Purposes for which the keys are rotated. Must include both 'auth' and 'attest'.

object

WebAuthn credentials for Human passport key rotation.

Responses

Request samples

Content type
application/json

Rotating keys for a Human passport with valid WebAuthn credentials.

{
  • "purposes": [
    ],
  • "webauthn": {
    }
}

Response samples

Content type
application/json
{
  • "passport_id": "did:human:123456789abcdef",
  • "status": "rotated",
  • "auth_key_id": "key_abcdef123456",
  • "attest_key_id": "key_123456abcdef",
  • "retired_at": "2023-10-15T08:55:30Z"
}

Enroll Guardian Recovery for Human Passport

Secure your digital identity with the power of community. This endpoint allows a human passport owner to establish a guardian-based recovery policy. By enlisting trusted guardians, you ensure a safety net for identity recovery, harnessing the strength of social verification.

Request Body schema: application/json
required
required
Array of objects [ 3 .. 5 ] items

An array of 3 to 5 guardian objects.

threshold
integer >= 2

Number of guardians required to approve a recovery.

Responses

Request samples

Content type
application/json

Enrolls three guardians with a threshold of two for recovery.

{
  • "guardians": [
    ],
  • "threshold": 2
}

Response samples

Content type
application/json
{
  • "policy_id": "policy_12345",
  • "type": "guardian",
  • "threshold": 2,
  • "guardians": [
    ],
  • "sss_enabled": true,
  • "sss_guardian_count": 3
}

Retrieve Passport Recovery Requests

In the world of digital identity, recovery is paramount. This endpoint lets you peek into the requests for recovering a passport, ensuring your digital identity's safety. Dive into a list of recovery attempts to audit and maintain control over your cryptographic identity.

Responses

Response samples

Content type
application/json

An example response showcasing a typical list of recovery requests.

{
  • "data": [
    ],
  • "pagination": {
    }
}

Generate Single-Use Recovery Keys

In the labyrinth of identity, sometimes you need a lifeline. This endpoint crafts a new set of 10 single-use recovery keys for your passport, ensuring you can always find your way back. These keys are your safety net, providing a secure way to regain access when all else fails. The keys are delivered just once, like a message in a bottle, so keep them safe.

Responses

Response samples

Content type
application/json

An example of a successful recovery key generation for a user's passport.

{
  • "recovery_keys": [
    ],
  • "count": 10,
  • "warning": "These keys are displayed only once. Store them securely."
}

Regenerate Passport Recovery Keys

In the ever-evolving landscape of digital identities, keeping your recovery keys secure is paramount. This endpoint gives you the power to regenerate your recovery keys, seamlessly revoking the old set and ensuring your digital identity remains protected. It's about safeguarding your credentials with a simple request.

Responses

Response samples

Content type
application/json

A user from the 'acme' organization successfully regenerates their recovery keys.

{
  • "recovery_keys": [
    ],
  • "count": 3,
  • "warning": null
}

Retrieve Remaining Recovery Keys

In the realm of digital identity, safeguarding access is paramount. This endpoint empowers users to check the status of their recovery keys without revealing sensitive details, ensuring they maintain a robust security posture. By understanding the balance of used, remaining, and total keys, users can navigate their recovery strategy with confidence.

Responses

Response samples

Content type
application/json

A response indicating the user has used some of their recovery keys.

{
  • "total": 5,
  • "remaining": 3,
  • "used": 2,
  • "generated": "2023-10-05T14:48:00.000Z"
}

Execute Passport Recovery Process

Unlock access to your digital identity with a secure, two-step recovery process. Using a single-use recovery key, this endpoint enables users to regain control of their Passport when their primary passkey is lost. Experience peace of mind with aggressive security measures protecting against unauthorized access.

Request Body schema: application/json
required
One of
step
required
string
Value: "initiate"
passport_hint
required
string

Hint for the passport identity, typically an email or DID

recovery_key
required
string

Single-use recovery key provided during initial setup

Responses

Request samples

Content type
application/json
Example

Example of the initial recovery request with recovery key and passport hint.

{
  • "step": "initiate",
  • "passport_hint": "user@example.com",
  • "recovery_key": "recovery-key-1234"
}

Response samples

Content type
application/json
Example
{
  • "registration_id": "reg-9876",
  • "options": {
    },
  • "recovery_token": "token-5678"
}

Retrieve Passport Consent Events

Explore the consent history of a cryptographic identity with precision and insight. This endpoint unveils the trail of consent events linked to a passport, showcasing how various resources have been accessed and utilized with explicit permissions. It empowers users to audit and understand the access patterns associated with their digital identity.

Responses

Response samples

Content type
application/json

Retrieve a paginated list of consent events for a digital passport.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Link Passport to Organization

In the world of HUMAN, identities are not just cryptographic tokens; they are passports to new opportunities. This endpoint links a user's cryptographic identity to their organizational role, ensuring that the right skills and capabilities are attributed to the right person. It's a vital step in creating a seamless Human-AI collaboration environment.

Request Body schema: application/json
required
linkingCode
required
string

A unique code provided by the organization to link the passport.

email
required
string <email>

The email address associated with the passport holder's organizational role.

Responses

Request samples

Content type
application/json

A request to link a passport with a valid linking code and email.

{
  • "linkingCode": "abc123-orglink",
  • "email": "john.doe@acme.org"
}

Response samples

Content type
application/json
{
  • "message": "Verification code sent to email",
  • "email": "john.doe@acme.org"
}

Verify email and complete passport link

This endpoint breathes life into the digital identity by verifying an email using a 6-digit code. It completes the vital connection between a passport and an organization, triggering an attestation that signals a trustworthy relationship. No additional authentication is needed beyond the code, making the process seamless and efficient.

Request Body schema: application/json
required
code
required
string

A 6-digit verification code sent to the user's email.

Responses

Request samples

Content type
application/json

Submits a 6-digit code to verify and link the email.

{
  • "code": "123456"
}

Response samples

Content type
application/json
null

Change founders synchronously with signatures

Join forces in a ceremonial moment to alter the fabric of your organization's leadership. This endpoint allows for immediate founder adjustments when all necessary signatures are provided, ensuring trust and authenticity in high-stakes decisions.

Request Body schema: application/json
required
action
required
string
Enum: "add" "remove"

Action to perform: 'add' to include a new founder, 'remove' to exclude an existing one.

founder_did
required
string^did:human:.*$

DID of the founder to be added or removed.

requested_by
required
string^did:human:.*$

DID of the founder proposing the change.

required
Array of objects

Array of signatures from current founders verifying the change.

Responses

Request samples

Content type
application/json

Example of adding a new founder to the organization with all required signatures.

{
  • "action": "add",
  • "founder_did": "did:human:12345",
  • "requested_by": "did:human:67890",
  • "signatures": [
    ]
}

Response samples

Content type
application/json
{
  • "org_did": "did:human:org:abcdef",
  • "action": "add",
  • "founder": {
    },
  • "founder_count": 4,
  • "threshold_required": 3,
  • "verified_approvers": [
    ],
  • "provenance_id": "prov_123456789"
}

Initiate domain verification for an organization

Verify an organization's domain as part of its cryptographic identity within the HUMAN Protocol. This process ensures the authenticity of the domain ownership, enhancing trust and security in AI-human task orchestration.

Request Body schema: application/json
required
One of
org_did
required
string^did:org:.*$

The Decentralized Identifier (DID) of the organization

domain
required
string

The domain name to be verified

Responses

Request samples

Content type
application/json

Initiating domain verification for Acme Corp.

{
  • "org_did": "did:org:acme",
  • "domain": "acmecorp.com"
}

Response samples

Content type
application/json
null

Initiate a Quorum Change Proposal

Empower organizational founders with the ability to propose pivotal changes in governance. This endpoint facilitates the creation of proposals for adding or removing founders, adjusting quorum thresholds, or even dissolving the organization. It's a crucial mechanism for dynamic and secure decision-making within decentralized environments.

Request Body schema: application/json
required
change_type
required
string
Enum: "add_founder" "remove_founder" "change_threshold" "dissolve"

The type of change being proposed

proposed_by
required
string

DID of the founder proposing the change

object
expires_in_hours
integer

Proposal expiration time in hours

signature
string

Valid Ed25519 signature over the proposal payload

Responses

Request samples

Content type
application/json

Proposing the addition of a new founder to the organization

{
  • "change_type": "add_founder",
  • "proposed_by": "did:human:12345",
  • "payload": {
    },
  • "expires_in_hours": 48,
  • "signature": "base64-encoded-signature"
}

Response samples

Content type
application/json
null

Verify a complete authority chain

In the intricate dance between human and AI, ensuring trustworthiness is paramount. This endpoint verifies the cryptographic integrity of an authority chain, documenting each step in the provenance ledger. Whether you're verifying an organization or an individual agent, this process guarantees that only legitimate entities hold power.

Request Body schema: application/json
required
One of
agent_did
required
string

Decentralized Identifier for the agent.

org_did
string

Decentralized Identifier for the organization.

mode
string
Enum: "full" "cached" "delegation-only"

Verification mode: full, cached, or delegation-only.

Responses

Request samples

Content type
application/json
Example

Verify the authority chain for an individual agent.

{
  • "agent_did": "did:agent:1234abcd",
  • "mode": "full"
}

Response samples

Content type
application/json

An agent's authority chain verified with no issues.

{
  • "agent_did": "did:agent:1234abcd",
  • "verification_mode": "full",
  • "valid": true,
  • "chain": {
    },
  • "errors": [ ],
  • "verified_at": "2023-10-04T14:48:00.000Z"
}

Verify biometric identity via webhook

This endpoint is the critical touchpoint where human and machine meet to ensure identity integrity. It enables seamless biometric verification, elevating the user's verification and identity tier while safeguarding against fraud through cryptographic checks.

Responses

Response samples

Content type
application/json

The biometric verification was successful, advancing verification and identity tiers.

{
  • "received": true,
  • "status": "clear"
}

Submit a signed vouch for identity

In a digital world, trust is invaluable. This endpoint allows trusted agents to vouch for a cryptographic identity, contributing to its social verification. Achieving a certain number of vouches can elevate the identity's verification tier, enhancing its credibility within the HUMAN ecosystem.

Request Body schema: application/json
required
voucher_did
required
string

Decentralized Identifier (DID) of the voucher

statement
required
string

A statement explaining the reason for the vouch

confidence
required
string
Enum: "high" "medium" "low"

Level of confidence in the vouch

relationship
required
string
Enum: "colleague" "friend" "family" "other"

The type of relationship with the subject

met_since
string <date-time>

Date since the voucher knows the subject

signature
required
string

Ed25519 signature of the vouch statement

timestamp
string <date-time>

Timestamp of when the vouch was created

Responses

Request samples

Content type
application/json

A vouch from a colleague with high confidence.

{
  • "voucher_did": "did:human:987654321abcdef",
  • "statement": "I have collaborated with them on multiple successful projects.",
  • "confidence": "high",
  • "relationship": "colleague",
  • "met_since": "2015-03-15T00:00:00Z",
  • "signature": "base64urlencodedstring",
  • "timestamp": "2023-10-10T14:48:00Z"
}

Response samples

Content type
application/json

A successful vouch submission that advanced the subject's verification tier.

{
  • "vouch_id": "pvo1234567890abcdef",
  • "active_vouches": 3,
  • "tier_3_achieved": true
}

Retrieve active vouches for a passport

Explore the trusted network around a passport by listing its active vouches. Discover how others in the HUMAN ecosystem vouch for this identity, building a web of trust that strengthens the protocol's integrity.

Responses

Response samples

Content type
application/json

Retrieve active vouches for the given passport ID

{
  • "data": [
    ],
  • "limit": 10,
  • "next_cursor": null
}

Revoke a self-authored vouch.

In the intricate dance of identity verification, a vouch represents trust. This endpoint allows a voucher to withdraw their endorsement, recalibrating the trust network if necessary. If the withdrawal dips below a critical threshold, the verification tier is gracefully demoted, ensuring the integrity of the ecosystem.

Responses

Response samples

Content type
application/json

A voucher revokes their support for a passport DID, reducing the active vouches.

{
  • "revoked": true,
  • "remaining_active_vouches": 1
}

Retrieve Encrypted Shamir Shard for Recovery

Guardians play a crucial role in the HUMAN network, ensuring the security and recovery of cryptographic identities. This endpoint allows a guardian to access their encrypted Shamir shard, a vital piece for identity recovery. Once decrypted client-side, the shard helps reconstruct the user's identity, safeguarding against data loss.

Responses

Response samples

Content type
application/json
{
  • "request_id": "req_123456",
  • "shard_index": 2,
  • "encrypted_shard_b64": "c2hhcmRfZW5jcnlwdGVkX2RhdGE=",
  • "ephemeral_public_key_b64": "ZXBoZW1lcmFsX3B1YmtleQ==",
  • "iv_b64": "aW5pdGlhbF92ZWN0b3I="
}

Complete Guardian Recovery Process

Unlock your digital identity by completing the guardian recovery process. This endpoint is the final step in securing your Passport's credentials after meeting the quorum of guardians and waiting for the lock period to expire. It's not just a transaction—it's the rebirth of trust and security in your digital realm.

Request Body schema: application/json
required
registration_id
required
string

Unique identifier for the new device registration.

required
object

Cryptographic credential for the new device.

Responses

Request samples

Content type
application/json

Completing recovery for a user moving credentials to a new device.

{
  • "registration_id": "reg_123456789",
  • "credential": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Guardian recovery completed successfully."
}

Store Encrypted Recovery Backup

Preserve your digital identity's resilience by securely storing an encrypted recovery backup for your HUMAN Passport. This ensures you can recover your cryptographic identity even if local credentials are lost, without compromising your passphrase.

Request Body schema: application/json
required
encrypted_blob
required
string

AES-256-GCM encrypted data blob

storage_hint
string
Enum: "icloud" "gdrive" "onedrive" "other"

Optional storage provider hint

Responses

Request samples

Content type
application/json

A typical encrypted backup to Google Drive

{
  • "encrypted_blob": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ...",
  • "storage_hint": "gdrive"
}

Response samples

Content type
application/json

Response indicating successful storage of encrypted backup.

{
  • "stored": true,
  • "updated_at": "2023-10-12T07:20:50.52Z"
}

Restore encrypted cloud backup

This endpoint allows users to securely restore their encrypted cloud backup for a passport, ensuring data sovereignty and privacy. By leveraging WebAuthn authentication, it verifies device ownership, facilitating client-side decryption and maintaining the integrity of sensitive information.

Responses

Response samples

Content type
application/json

A user successfully retrieves their encrypted cloud backup for decryption.

{
  • "encrypted_blob": "U2FsdGVkX1+I5Jql7Q==",
  • "storage_hint": "us-east-1",
  • "backed_up_at": "2023-10-15T14:48:00Z"
}

Verify Verifiable Credential for Passport

Elevate your digital identity by submitting a Verifiable Credential, pushing your identity tier to 3. This endpoint verifies credentials from trusted issuers, ensuring your identity is both secure and recognized. An advanced identity tier opens doors to more opportunities within the HUMAN ecosystem.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json

A credential submission for an identity verification.

{
  • "credential": {
    }
}

Response samples

Content type
application/json
{
  • "identity_tier": 3,
  • "credential_id": "cred-12345"
}

Initiate Proof of Personhood verification

Embark on a journey to establish the authenticity of an individual's identity through the Proof of Personhood process. This operation ensures that the passport in question truly belongs to a human, reinforcing trust in the HUMAN network.

Responses

Response samples

Content type
application/json

Initiating a session for Proof of Personhood verification.

{}

Verify Proof of Personhood via Webhook

This endpoint receives and processes the Proof of Personhood (PoP) verification from a provider. By advancing the verification tier to 4, it ensures the cryptographic identity represented by a Passport is uniquely tied to a human, preventing duplicate identities in the HUMAN ecosystem.

Request Body schema: application/json
required
nullifierHash
required
string

Unique hash representing the verified individual.

provider
required
string

The PoP provider processing the request.

signature
string

Signature verifying the authenticity of the webhook call.

Responses

Request samples

Content type
application/json

A typical PoP verification result from the provider.

{
  • "nullifierHash": "abc123xyz456",
  • "provider": "trusted_pop_provider",
  • "signature": "signed_payload_hash"
}

Response samples

Content type
application/json
{
  • "received": true,
  • "status": "verified",
  • "verification_tier": 4
}

Create a Passport Disclosure Request

Submit a request for specific attribute disclosures from a HUMAN passport. This endpoint empowers organizations to verify identity claims while respecting user consent and privacy policies, ensuring a secure and transparent process.

Request Body schema: application/json
required
requester_did
required
string

DID of the entity requesting disclosure

requested_claims
required
object

Attributes being requested for disclosure

purpose
required
string

Purpose for requesting the disclosure

expires_in_seconds
required
integer

Time in seconds until the request expires

proof_type
required
string

Type of proof required for the disclosure

range_proofs
object

Optional range proofs for verifying claims

Responses

Request samples

Content type
application/json

A request for verifying age attribute with a proof type of 'zero-knowledge'.

{
  • "requester_did": "did:human:acme:org",
  • "requested_claims": {
    },
  • "purpose": "Verify age for age-restricted service",
  • "expires_in_seconds": 3600,
  • "proof_type": "zero-knowledge",
  • "range_proofs": {
    }
}

Response samples

Content type
application/json
{
  • "request_id": "pdr_12345",
  • "status": "pending",
  • "created_at": "2023-10-01T10:00:00Z",
  • "expires_at": "2023-10-01T11:00:00Z",
  • "proof_type": "zero-knowledge",
  • "consent_policy_id": "policy_6789"
}

Retrieve pending disclosures for a Passport

Explore the intricacies of managing digital identity by retrieving pending disclosure requests linked to a specific Passport. This endpoint allows users to track and manage requests, ensuring transparency and control over their personal data.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Deny a disclosure request for a passport

In the dance of identity and privacy, sometimes a request must be refused. This endpoint allows a passport holder to deny a pending disclosure request, ensuring that only the rightful owner can manage their personal information. It's a safeguard in the HUMAN protocol's commitment to user autonomy and privacy.

Responses

Response samples

Content type
application/json
null

Complete Device Sync for Passport

Securely finalize the synchronization of a new device with your HUMAN Passport, ensuring the integrity of cryptographic identity at every step. This endpoint not only validates the device's credentials but also reinforces trust through stringent attestation checks.

Request Body schema: application/json
required
session_id
required
string

Session ID for the sync process.

device_attestation
required
string

JWT for attesting the device's validity.

new_device_name
required
string <= 100 characters

A human-readable identifier for the new device.

new_device_public_key
required
string

Public key associated with the new device.

Responses

Request samples

Content type
application/json

Example of completing device sync for a new device named 'AcmeLaptop'.

{
  • "session_id": "abc123-session",
  • "device_attestation": "eyJhbGciOiJIUzI1NiIsInR...",
  • "new_device_name": "AcmeLaptop",
  • "new_device_public_key": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBA..."
}

Response samples

Content type
application/json
{
  • "device_id": "device-12345",
  • "enrolled_at": "2023-10-01T12:45:00Z"
}

Verify Passport Ledger Anchor Inclusion

Ensure your digital identity's anchoring is secure by verifying its inclusion in the blockchain's Merkle tree. This endpoint empowers users to authenticate their Passport's ledger integrity, reinforcing trust in decentralized identity management.

Request Body schema: application/json
required
required
Array of objects
leaf_hash
required
string^0x[a-fA-F0-9]{64}$

Responses

Request samples

Content type
application/json

A valid Merkle proof with corresponding leaf hash for identity verification.

{
  • "merkle_proof": [
    ],
  • "leaf_hash": "0xabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcd"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "on_chain_ref": {
    }
}

Retrieve BBS+ Issuer Verification Key

Unveil the powerful BBS+ issuer verification key, designed for offline verifiers to ensure trust without the tether of constant connectivity. By accessing this endpoint, you empower decentralized identity systems to validate credentials authentically and securely.

Responses

Response samples

Content type
application/json

Retrieve the BBS+ issuer verification key for offline verification.

{
  • "keys": [
    ]
}

Accept Guardian Role for Passport Recovery

In the intricate dance of Human-AI orchestration, ensuring a secure recovery process is paramount. This endpoint allows a guardian to accept their role in the recovery of a passport, downloading an encrypted shard bundle to their device. By acknowledging this responsibility, guardians protect the sanctity of digital identities.

Responses

Response samples

Content type
application/json

A guardian successfully accepts their role and receives the encrypted shard.

{
  • "request_id": "req_12345",
  • "passport_did": "did:human:abc123",
  • "guardian_did": "did:human:guardian456",
  • "shard_index": 1,
  • "encrypted_shard_b64": "VGhpcyBpcyBhbiBlbmNyeXB0ZWQgc2hhcmQ=",
  • "ephemeral_public_key_b64": "RW5jcnlwdGVkIFB1YmxpYyBLZXk=",
  • "iv_b64": "SW5pdCBWZWN0b3I=",
  • "delivered_to_device": true
}

Fetch Passport Device Revocation Snapshot

Retrieve a cryptographic snapshot of revoked devices for a given Human Passport. This endpoint empowers offline verifiers by providing them with a cached list of device IDs that have been revoked, ensuring the integrity and validity of AI orchestrations.

Responses

Response samples

Content type
application/json

Fetching the revocation snapshot for an active passport.

{
  • "passport_did": "did:human:123456789abcdefghi",
  • "revoked_device_ids": [
    ],
  • "snapshot_at": "2023-10-15T12:00:00.000Z",
  • "expires_at": "2023-10-16T12:00:00.000Z",
  • "content_sha256": "5d41402abc4b2a76b9719d911017c592",
  • "hub_public_key": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQD...",
  • "hub_signature": "MEUCIQDy9...aR+Q==",
  • "canonical_message": "revocation-snapshot|did:human:123456789abcdefghi|2023-10-15T12:00:00.000Z|5d41402abc4b2a76b9719d911017c592"
}

Retrieve Capability Graph for a Passport

Explore the vast landscape of skills associated with a given Passport ID within the HUMAN ecosystem. This endpoint unveils the intricate web of capabilities that an identity can wield, offering insights into their potential interactions within the network.

Responses

Response samples

Content type
application/json

An example response showing the capabilities of a Passport ID.

{
  • "passportId": "passport-12345",
  • "capabilities": [
    ]
}

Retrieve active MCP sessions

Discover the active and valid sessions for your cryptographic identity with this endpoint. It's designed to empower organizations, like Acme Corp, by listing ongoing sessions securely linked to a Passport, ensuring transparency and control over session activity.

Responses

Response samples

Content type
application/json

An example response showing active sessions for a Passport.

{
  • "sessions": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Retrieve Active Principals for Passport

Uncover the identities your passport can embody, from personal to organizational alignments. This endpoint reveals all active principals linked to the authenticated passport, allowing you to navigate your roles with clarity.

Responses

Response samples

Content type
application/json

Retrieve principals for a passport linked to personal identity and Acme Corp.

{
  • "principals": [
    ],
  • "active_principal_id": "did:human:passport:123456789abcdef"
}

DID

Resolve a DID for the HUMAN platform

Dive into the world of decentralized identities with the HUMAN platform's DID resolution endpoint. This service allows you to retrieve a well-defined DID Document, crucial for establishing verifiable digital identities. It's a gateway to ensuring trust and authenticity in a decentralized ecosystem, enabling seamless human-AI interaction.

Responses

Response samples

Content type
application/json

A DID Document for the Acme Corporation's API service

{}

System

Retrieve System Capabilities Overview

Explore the dynamic landscape of your system's capabilities with this endpoint. As part of HUMAN's Capability Graph, it provides a comprehensive list of all defined actions, resources, and constraints, helping you understand and manage the skills within your distributed network. This is crucial for aligning your technological ecosystem with strategic goals.

Responses

Response samples

Content type
application/json

An organization discovers its system capabilities to align with its strategic initiatives.

{
  • "capabilities": [
    ],
  • "count": 2
}

Capabilities

Retrieve System Capabilities Overview

Explore the dynamic landscape of your system's capabilities with this endpoint. As part of HUMAN's Capability Graph, it provides a comprehensive list of all defined actions, resources, and constraints, helping you understand and manage the skills within your distributed network. This is crucial for aligning your technological ecosystem with strategic goals.

Responses

Response samples

Content type
application/json

An organization discovers its system capabilities to align with its strategic initiatives.

{
  • "capabilities": [
    ],
  • "count": 2
}

Retrieve available AI models and capabilities

Explore the dynamic landscape of AI models with HUMAN's orchestration endpoint. By filtering models based on provider, status, and capabilities, organizations can harness the right blend of reasoning and coding prowess to meet their unique needs. This endpoint serves as a gateway to understanding and leveraging the diverse skills housed within the HUMAN network.

Responses

Response samples

Content type
application/json

Acme Corp is filtering models by OpenAI provider and active status, seeking top-tier reasoning capabilities.

{
  • "models": [
    ]
}

Invoke an extension's capability for action

Unlock the potential of your organization's installed extensions by invoking specific capabilities. This endpoint is the gateway to extending functionality, allowing you to orchestrate tasks and actions with precision and control. It exists to seamlessly integrate and activate the diverse capabilities within your distributed AI systems.

Request Body schema: application/json
required
capability
required
string

The capability to be invoked, identified by a URI

action
string

The action to perform using the capability

params
object

Parameters required for the action

Responses

Request samples

Content type
application/json

Invoke the 'processInvoice' capability to automate invoice handling for the 'acme' organization.

{
  • "capability": "capability://acme/invoice/process",
  • "action": "process",
  • "params": {
    }
}

Response samples

Content type
application/json
null

Resolve Workflow Capabilities

This endpoint is the conductor in an orchestra of capabilities, harmonizing the skills required for each step in a workflow. It ensures that only the most suitable connectors are employed, optimizing efficiency and precision in task execution.

Request Body schema: application/json
required
include_trace
boolean

Whether to include trace information for debugging.

Responses

Request samples

Content type
application/json

An example where trace information is requested.

{
  • "include_trace": true
}

Response samples

Content type
application/json

A successful resolution of capabilities for a workflow step.

{
  • "resolutions": [
    ]
}

Upgrade Workflow Step to Capability

Elevate your workflow step by enhancing its capabilities. This endpoint allows an organization to upgrade a specific step in a workflow, ensuring it meets new requirements and capabilities essential for advanced processing. By harnessing the power of the Capability Graph, organizations can track and adapt skill requirements dynamically.

Request Body schema: application/json
required
required_capabilities
required
Array of strings
required_connectors
Array of strings

Responses

Request samples

Content type
application/json

Upgrade the workflow step to include 'capability://ai.ocr' and 'capability://data.validation'.

{
  • "required_capabilities": [
    ],
  • "required_connectors": [
    ]
}

Response samples

Content type
application/json
{
  • "workflow": {
    },
  • "rung_before": 2,
  • "rung_after": 3
}

Retrieve active capabilities by intent family

Dive into the world of HUMAN's orchestration, where each capability is a piece in the grand puzzle of AI and human collaboration. This endpoint fetches active capabilities tailored to a specified intent family, allowing organizations to seamlessly integrate the right skills for their needs.

Responses

Response samples

Content type
application/json

Shows capabilities for the 'set_up_automation' intent family.

{
  • "intent_family": "set_up_automation",
  • "count": 2,
  • "data": [
    ]
}

Batch Query Capabilities for Tasks

Unlock the potential of your enterprise by efficiently querying capabilities across multiple tasks. This endpoint orchestrates a seamless interaction between human and AI capabilities, ensuring the right skills are matched to each task. It empowers organizations to harness their full potential by dynamically leveraging a distributed ledger of skills.

Request Body schema: application/json
required
org_id
required
string

Unique identifier for the organization.

required
Array of objects

Array of tasks with required capabilities.

object

Responses

Request samples

Content type
application/json

A query for Acme Corp to find capabilities for tasks.

{
  • "org_id": "acme-corp",
  • "queries": [
    ],
  • "options": {
    }
}

Response samples

Content type
application/json
null

Match Capabilities for Task Routing

Efficiently orchestrate tasks by matching required capabilities to available humans and agents. This endpoint leverages a sophisticated algorithm to ensure that the right skills are applied to the right tasks, enhancing productivity and ensuring AI safety.

Request Body schema: application/json
required
required_capabilities
required
Array of strings

List of capability IDs required for the task.

org_id
required
string

The organization ID where the task is to be routed.

min_confidence
number [ 0 .. 1 ]
Default: 0.5

Minimum confidence level for matching capabilities.

include_humans
boolean
Default: true

Whether to include human resources in the match.

include_agents
boolean
Default: true

Whether to include AI agents in the match.

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of matches to return.

match_strategy
string
Default: "exact"
Enum: "exact" "semantic" "hybrid"

Strategy to use for matching capabilities.

task_description
string

Description of the task, required if using semantic or hybrid strategy.

task_id
string
Default: "inline"

Unique identifier for the task.

Responses

Request samples

Content type
application/json

A request to match capabilities with a minimum confidence of 0.7 in the 'acme' organization using an exact match strategy.

{
  • "required_capabilities": [
    ],
  • "org_id": "org_acme",
  • "min_confidence": 0.7,
  • "include_humans": true,
  • "include_agents": true,
  • "limit": 10,
  • "match_strategy": "exact"
}

Response samples

Content type
application/json

An example of a successful match with humans and agents for invoice processing.

{
  • "humans": [
    ],
  • "agents": [
    ],
  • "capability_gap": false,
  • "query": {
    },
  • "matched_count": 3,
  • "match_strategy_used": "exact",
  • "weakest_link_score": 0.85,
  • "threshold_used": 0.7,
  • "routed": true,
  • "resolved_canonical": [
    ],
  • "semantic_skipped": false
}

Retrieve routing capabilities for tasks

Uncover the harmony between AI and human skills by identifying routing capabilities tailored to your organization's needs. This endpoint orchestrates the intricate dance of task routing by fetching a curated list of capabilities based on your specified criteria, ensuring optimal skill application and AI safety.

Responses

Response samples

Content type
application/json

Retrieving a list of capabilities for the 'acme' organization with specific routing needs.

{
  • "capabilities": [
    ],
  • "count": 1,
  • "org_slug": "acme",
  • "overlay": "canonical + org-scoped"
}

Search capability ontology

Dive into the depths of HUMAN's Capability Graph with this endpoint, crafted to unearth the skills and attributes hidden within our ontology. Whether you're matching precise skills or exploring broader categories, this search tool is your gateway to understanding and utilizing HUMAN's rich skill taxonomy.

Responses

Response samples

Content type
application/json

A search for 'invoice processing' in the ontology.

{
  • "results": [
    ],
  • "total": 1,
  • "query_embedding_cached": false
}

Retrieve canonical capability details

In the intricate dance of human and AI collaboration, understanding the core capabilities is paramount. This endpoint reveals the canonical form of an organizational capability, ensuring clarity and consistency across the HUMAN ecosystem. By resolving to a canonical URI, it provides a solid reference point in the ever-evolving capability graph.

Responses

Response samples

Content type
application/json
{
  • "canonicalUri": "capability://acme/finance/invoice-processing",
  • "description": "Processes financial invoices for Acme Corp."
}

Propose updates to a capability ontology

Engage with the HUMAN protocol by proposing canonical updates to a capability. This endpoint empowers users to enhance the system's understanding of a skill, ensuring the AI aligns closer with human expertise.

Request Body schema: application/json
required
name
required
string

The new name for the capability.

description
required
string

A detailed explanation of the capability's function.

attributes
Array of strings

List of attributes that define the capability.

Responses

Request samples

Content type
application/json

Propose a new name and description for a capability.

{
  • "name": "Advanced Image Analysis",
  • "description": "A capability for processing and interpreting complex image data.",
  • "attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Proposal submitted successfully."
}

Promote capability to canonical status

Elevate an organizational capability to a canonical status, ensuring it becomes a recognized skill within the HUMAN ecosystem. This endpoint fosters standardization and interoperability by allowing organizations to formalize their unique skills for broader use.

Request Body schema: application/json
required
canonical_uri
required
string

The URI that uniquely identifies the canonical form of the capability.

promoter_did
required
string

DID of the agent promoting the capability.

Responses

Request samples

Content type
application/json

An example of promoting the InvoiceProcessing capability to canonical, with a specific URI and promoter DID.

{
  • "canonical_uri": "capability://acme/invoice-processing",
  • "promoter_did": "did:example:123456789abcdefghi"
}

Response samples

Content type
application/json
{
  • "org_cap_id": "cap_67890",
  • "status": "promoted",
  • "canonical_uri": "capability://acme/invoice-processing",
  • "deprecated_org_uri": "org://acme/legacy-invoice-processing",
  • "provenance_event_id": "pe_1697043000000"
}

Infer capabilities for a digital identity

Harness the power of HUMAN's Capability Graph to dynamically infer the skills associated with a digital identity, identified by its DID. This endpoint empowers organizations to efficiently manage and update the skill sets of their digital agents, ensuring they are always aligned with the latest operational needs.

Request Body schema: application/json
required
org_id
required
string

The organization ID to scope the capability inference.

Responses

Request samples

Content type
application/json

Requesting capability inference for Acme Corp's digital identity.

{
  • "org_id": "acme-corp-123"
}

Response samples

Content type
application/json

The capabilities were inferred successfully for the specified DID.

{
  • "proposals_created": 5,
  • "proposals_updated": 3,
  • "did": "did:human:123456789abcdefghi",
  • "ran_at": "2023-10-25T14:48:00Z"
}

Retrieve capability proposals for a DID

Explore the landscape of your digital capabilities with this endpoint. By retrieving proposals associated with a Decentralized Identifier (DID), you can track the evolution of skills and knowledge as they align with your digital identity. This empowers organizations to make informed decisions about skill development and deployment.

Responses

Response samples

Content type
application/json

ACME Corp retrieves the latest 50 capability proposals for DID 'did:example:123456789abcdefghi'.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Accept a Capability Proposal

In the dynamic world of Human-AI collaboration, the acceptance of capability proposals solidifies the partnership between human agents and AI systems. This endpoint empowers authorized reviewers to formally accept proposals, thereby expanding the skill set recognized within the HUMAN platform.

Request Body schema: application/json
required
reviewer_did
required
string

The decentralized identifier of the reviewer accepting the proposal.

Responses

Request samples

Content type
application/json

Acceptance of a capability proposal with a valid reviewer DID.

{
  • "reviewer_did": "did:human:example123"
}

Response samples

Content type
application/json
null

Reject a capability proposal

This endpoint allows a reviewer to reject a capability proposal, ensuring that only appropriate skills are added to the Capability Graph. By empowering reviewers to provide feedback, HUMAN maintains a high standard of trust and reliability in its network.

Request Body schema: application/json
required
reviewer_did
required
string

Decentralized Identifier of the reviewer

rejection_reason
required
string

Reason for rejecting the proposal

Responses

Request samples

Content type
application/json

Rejecting a proposal with a valid reason

{
  • "reviewer_did": "did:human:abc123",
  • "rejection_reason": "Insufficient evidence of skill proficiency"
}

Response samples

Content type
application/json
null

Retrieve detailed capability ontology

Delve into the intricacies of a specific capability within the HUMAN ecosystem. This endpoint reveals the nuanced relationships and metadata that define a capability, providing a comprehensive view of its role and market dynamics. It's the key to unlocking how capabilities interconnect and evolve in response to market demands.

Responses

Response samples

Content type
application/json

An example highlighting a capability used by Acme Corp to enhance AI negotiation skills.

{
  • "id": "cap_ai_negotiation",
  • "canonical_name": "AI Negotiation",
  • "category": "AI Skills",
  • "subcategory": "Negotiation",
  • "domain": "Artificial Intelligence",
  • "description": "Enables AI systems to effectively negotiate agreements.",
  • "relationships": [
    ],
  • "metadata": {
    }
}

Retrieve capability definitions list

Uncover the breadth of skills tracked within the HUMAN ecosystem. This endpoint offers a window into the capabilities that define our dynamic landscape, with filters to cater to your specific interests—be it canonical, organizational, or a blend of both.

Responses

Response samples

Content type
application/json
{
  • "definitions": [
    ],
  • "count": 1
}

Create a new capability definition

Crafting a new capability is like sculpting the future of your organization. This endpoint empowers you to define the skills and tasks your AI can perform, embedding them into the HUMAN ecosystem. Use it to expand your capabilities and push the boundaries of what’s possible.

Request Body schema: application/json
required
id
required
string

A unique identifier for the capability

scope
required
string

The scope of the capability, e.g., 'canonical' or 'custom'

status
required
string

The status of the capability, e.g., 'active' or 'inactive'

Responses

Request samples

Content type
application/json

Creating a custom capability for invoice processing

{
  • "id": "capability_12345",
  • "scope": "custom",
  • "status": "active"
}

Response samples

Content type
application/json
null

Import capability definitions into HUMAN

Effortlessly expand your HUMAN capabilities by importing definitions. This endpoint empowers organizations to seamlessly introduce new capability structures, ensuring that your AI-human collaborations remain cutting-edge and adaptable. Whether you're avoiding conflicts or overwriting existing entries, this tool is designed to enhance your capability graph with ease.

Request Body schema: application/json
required
required
Array of objects

Array of capability definitions to be imported

conflict_strategy
string
Enum: "skip" "overwrite" "fail"

Strategy to handle conflicts with existing definitions

scope
string
Enum: "canonical" "org"

Scope of the import operation

Responses

Request samples

Content type
application/json

Example showing a typical import with conflict resolution strategy

{
  • "definitions": [
    ],
  • "conflict_strategy": "overwrite",
  • "scope": "org"
}

Response samples

Content type
application/json
null

Promote a Capability Definition

Elevate an organizational capability to a canonical level, ensuring its availability for broader use across the HUMAN platform. This action requires careful authorization and is recorded for provenance.

Request Body schema: application/json
required
canonicalId
required
string

The canonical ID for the capability to promote

justification
string

Reason for promoting this capability

approvedBy
required
string

Passport DID of the approving authority

Responses

Request samples

Content type
application/json

Promoting an 'Invoice Processing' capability to canonical status for broader ecosystem use.

{
  • "canonicalId": "cap_123456",
  • "justification": "High demand across multiple organizations",
  • "approvedBy": "did:human:1234abcd"
}

Response samples

Content type
application/json
{
  • "org_capability_id": "org_cap_7890",
  • "canonical_capability_id": "cap_123456",
  • "status": "promoted"
}

Retrieve available ontology packages

Dive into the world of HUMAN's ontology packages, where AI capabilities are meticulously organized and tracked. This endpoint offers a window into the published skill sets, empowering you to explore, evaluate, and integrate them seamlessly into your workflow.

Responses

Response samples

Content type
application/json

Fetching a list of ontology packages published by Acme Corp.

{
  • "packages": [
    ],
  • "count": 1
}

Retrieve specific capability package version

Delve into the rich tapestry of skills by fetching a specific version of a capability package. This endpoint is your gateway to understanding the evolution and offerings of a package within the HUMAN ecosystem, providing both provenance and potential.

Responses

Response samples

Content type
application/json

Retrieving the 'acme-invoice-processor' package version 1.2.0

{
  • "id": "acme-invoice-processor",
  • "version": "1.2.0",
  • "publisher": {
    },
  • "name": "Invoice Processor",
  • "description": "A powerful tool for processing and automating invoice workflows.",
  • "scope": "enterprise",
  • "license": "MIT",
  • "pricing": {
    },
  • "capability_count": 15,
  • "status": "active",
  • "changelog": "Added new OCR feature for faster invoice scanning.",
  • "created_at": "2023-08-10T14:48:00Z",
  • "published_at": "2023-09-01T10:00:00Z"
}

Generate a Capability Proof

Unlock the potential of your digital identity by generating a cryptographic proof of capabilities tied to your Passport. This endpoint ensures active capability grants, empowering secure and verifiable interactions across the HUMAN platform.

Request Body schema: application/json
required
did
required
string

Passport decentralized identifier (DID)

capabilities
required
Array of strings

List of capability identifiers to prove

proof_type
string
Default: "attestation"

Type of proof, defaults to 'attestation'

valid_for
integer

Duration in seconds for which the proof is valid

Responses

Request samples

Content type
application/json

Requesting a proof for specific capabilities linked to a Passport DID.

{
  • "did": "did:human:acme:12345",
  • "capabilities": [
    ],
  • "proof_type": "attestation",
  • "valid_for": 3600
}

Response samples

Content type
application/json

Proof created for a user's capabilities with a verification link.

{
  • "proof_id": "proof_67890",
  • "proof_data": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "capabilities_proven": [
    ],
  • "created_at": "2023-10-26T15:30:00Z",
  • "expires_at": "2023-10-26T16:30:00Z",
  • "verification_url": "https://verify.human.xyz/proofs/proof_67890"
}

Verify Capability Proofs for Authorization

In the HUMAN protocol, verifying capability proofs is essential for ensuring that agents possess the necessary skills to execute a task. This endpoint authenticates the validity of a submitted proof, safeguarding against expired, inactive, or mismatched data, and ensuring trust in the orchestration process.

Request Body schema: application/json
required
proof_id
required
string

The unique identifier for the capability proof.

proof_data
required
string

The cryptographic data associated with the capability proof.

Responses

Request samples

Content type
application/json

Validates that an agent from 'acme' organization has the verified capability to process invoices.

{
  • "proof_id": "proof-12345",
  • "proof_data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
null

Search for Capability Grants by Skills

Unleash the potential of your human and AI workforce by discovering capability grants that match specific skills and criteria. This endpoint allows you to find the right skill sets by filtering through various parameters, ensuring you connect with the most suitable capabilities for your needs.

Responses

Response samples

Content type
application/json

Acme Corp is looking for AI capabilities in data processing with a minimum confidence weight.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "meta": {
    }
}

Submit verifiable credential evidence

This endpoint empowers organizations to submit evidence of capabilities through verifiable credentials, establishing trust in a world where humans and AI collaborate seamlessly. It ensures that each capability is backed by cryptographic proof, enhancing the trustworthiness of skill attestations.

Request Body schema: application/json
required
passport_did
required
string

The decentralized identifier for the passport, serving as the canonical identity.

credential_id
required
string

The unique identifier of the verifiable credential being submitted.

required
Array of objects

An array of capabilities being attested, each with an optional attestation level.

Responses

Request samples

Content type
application/json

An organization 'acme' submits a credential that attests to an employee's skills in data analysis and project management.

{
  • "passport_did": "did:example:123456789abcdefghi",
  • "credential_id": "cred-123456",
  • "capabilities_attested": [
    ]
}

Response samples

Content type
application/json
{
  • "evidence_id": "cgcr-987654",
  • "status": "accepted",
  • "verification_status": "verified",
  • "passport_did": "did:example:123456789abcdefghi",
  • "credential_id": "cred-123456",
  • "capabilities_updated": [
    ],
  • "recorded_at": "2023-10-11T12:34:56Z"
}

Submit Capability Training Evidence

This endpoint is a gateway to empower learners by formalizing their educational milestones into recognized capabilities. By submitting evidence of training completion, you unlock new doors for skill acknowledgment within the HUMAN network, propelling your journey of continuous growth.

Request Body schema: application/json
required
passport_did
required
string

The Digital Identity (DID) of the learner's passport.

course_id
required
string

Identifier for the completed course.

completion_date
required
string <date-time>

Date when the course was completed, formatted as ISO 8601.

assessment_score
required
number [ 0 .. 1 ]

Score reflecting learner's performance, ranging from 0 to 1.

required
Array of objects

List of capabilities acquired from the course.

Responses

Request samples

Content type
application/json

A complete request showing how a learner's training completion can be submitted.

{
  • "passport_did": "did:human:123456789abcdefghi",
  • "course_id": "course-2023-xyz",
  • "completion_date": "2023-10-15T10:00:00Z",
  • "assessment_score": 0.85,
  • "capabilities_learned": [
    ]
}

Response samples

Content type
application/json
{
  • "evidence_id": "cgtr-20231015100000",
  • "status": "accepted",
  • "passport_did": "did:human:123456789abcdefghi",
  • "course_id": "course-2023-xyz",
  • "completion_date": "2023-10-15T10:00:00Z",
  • "assessment_score": 0.85,
  • "capabilities_updated": [
    ],
  • "recorded_at": "2023-10-15T10:05:00Z"
}

Retrieve monthly capability growth data

Explore the trajectory of a specific capability over time to understand patterns and make informed decisions. This endpoint provides a historical view of capability grants, helping organizations track their evolution and assess future trends.

Responses

Response samples

Content type
application/json

Retrieving growth data for capability 'invoice-processing' for DID 'did:example:acme123'.

{
  • "did": "did:example:acme123",
  • "capability_id": "invoice-processing",
  • "timeframe": "90d",
  • "data_points": [
    ],
  • "trend": "improving",
  • "growth_rate": "+5.88% vs prior weight",
  • "weight_source": "capability_node_weights",
  • "projection": {
    }
}

Retrieve skill growth recommendations

Unlock the potential of your digital identity by exploring tailored skill pathways. This endpoint guides you through suggested capabilities based on your current skill set, helping you navigate the ever-evolving landscape of human and AI symbiosis.

Responses

Response samples

Content type
application/json

Acme Corp employee with DID 'did:human:1234' receives skill recommendations to enhance their digital toolkit.

{
  • "did": "did:human:1234",
  • "recommendations": [
    ]
}

Retrieve active capabilities for a Passport DID

Uncover the skills and capabilities associated with a given Passport's DID. This endpoint helps you understand the active capabilities granted to an AI or human agent, providing insight into their skillset within the HUMAN platform.

Responses

Response samples

Content type
application/json

An example showing the retrieval of active capabilities for a given DID.

{
  • "passport_did": "did:human:1234abcd",
  • "grant_count": 2,
  • "grants": [
    ]
}

Query capabilities with complex filters

This endpoint empowers users to query the HUMAN Capability Graph using intricate filters, enabling the discovery of skill sets that match specific criteria. It provides flexibility for large filter sets, ensuring precision and depth in capability matching.

Request Body schema: application/json
required
required
Array of strings or string

A list of skills or a comma-separated string of skills to filter by.

limit
integer

Maximum number of results to return.

cursor
string

Opaque cursor for paginating results.

min_weight
number

Minimum confidence weight for filtering capabilities.

Array of strings or string

A list or comma-separated string of domains to filter within.

sort
string

Field(s) to sort results by.

experience_years__gte
string

Minimum years of experience for filtering.

Responses

Request samples

Content type
application/json

This example queries capabilities by specifying a list of skills and a domain.

{
  • "skills": [
    ],
  • "min_weight": 0.8,
  • "domains__in": "technology",
  • "limit": 10,
  • "sort": "-weight"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "meta": {
    }
}

Submit cross-border capability evidence

In the interconnected world of HUMAN, demonstrating skills across borders is crucial. This endpoint allows agents to submit evidence of their capabilities, verified internationally, to enhance their global reputation and unlock new opportunities. It's about breaking barriers and building a universal profile.

Request Body schema: application/json
required
agentId
required
string

Unique identifier for the agent submitting evidence

evidenceType
required
string
Enum: "certification" "work-sample" "testimonial"

Type of evidence being submitted

required
object

Detailed data of the evidence

Responses

Request samples

Content type
application/json

An agent submits a certification as evidence

{}

Response samples

Content type
application/json
null

Verify capabilities within the graph

In the realm of human-AI collaboration, knowing who can do what is crucial. This endpoint verifies whether a specific capability exists within an agent's graph, ensuring tasks are routed to the right human or AI. By validating capabilities, we maintain trust and accuracy in AI-driven workflows.

Request Body schema: application/json
required
agentId
required
string

The unique identifier for the agent whose capabilities are being verified.

capabilityId
required
string

The unique identifier of the capability to be verified.

Responses

Request samples

Content type
application/json

This example checks if the 'data-processing' capability exists for agent 'agent-123'.

{
  • "agentId": "agent-123",
  • "capabilityId": "data-processing"
}

Response samples

Content type
application/json
null

Retrieve Capability Graph for a Passport

Explore the vast landscape of skills associated with a given Passport ID within the HUMAN ecosystem. This endpoint unveils the intricate web of capabilities that an identity can wield, offering insights into their potential interactions within the network.

Responses

Response samples

Content type
application/json

An example response showing the capabilities of a Passport ID.

{
  • "passportId": "passport-12345",
  • "capabilities": [
    ]
}

Control Plane

Retrieve System Capabilities Overview

Explore the dynamic landscape of your system's capabilities with this endpoint. As part of HUMAN's Capability Graph, it provides a comprehensive list of all defined actions, resources, and constraints, helping you understand and manage the skills within your distributed network. This is crucial for aligning your technological ecosystem with strategic goals.

Responses

Response samples

Content type
application/json

An organization discovers its system capabilities to align with its strategic initiatives.

{
  • "capabilities": [
    ],
  • "count": 2
}

Create a new organization in the HUMAN protocol

This endpoint orchestrates the creation of a new organization, weaving together identity, skills, and AI safety into a cohesive entity. It serves as the gateway for enterprising teams to join the HUMAN network, enabling them to harness distributed ledger technology for provenance and task orchestration.

Request Body schema: application/json
required
org_did
required
string

Decentralized identifier for the organization.

name
required
string

Human-readable name of the organization.

slug
string

URL-friendly identifier, optional.

deployment_mode
string
Enum: "cloud" "on-prem"

Deployment preference, default is 'cloud'.

data_residency_tier
string
Enum: "global" "regional"

Desired data residency policy, default is 'global'.

autonomy_profile
string
Enum: "balanced" "high" "low"

Autonomy level for AI task routing, default is 'balanced'.

Responses

Request samples

Content type
application/json

Creating an organization for Acme Corp with default settings.

{
  • "org_did": "did:org:acme-corp",
  • "name": "Acme Corp",
  • "slug": "acme-corp",
  • "deployment_mode": "cloud",
  • "data_residency_tier": "global",
  • "autonomy_profile": "balanced"
}

Response samples

Content type
application/json
{
  • "org_did": "did:org:acme-corp",
  • "name": "Acme Corp",
  • "slug": "acme-corp",
  • "deployment_mode": "cloud",
  • "data_residency_tier": "global",
  • "autonomy_profile": "balanced",
  • "member_roles": {
    },
  • "vault_endpoint": "https://api.humanprotocol.com/v1/vault"
}

Retrieve pending escalation requests

Navigate the intricate web of organizational approvals by fetching escalation requests awaiting attention. Designed for orchestrating critical decision points, this endpoint empowers users to manage and respond to escalated tasks, ensuring timely resolutions and maintaining workflow integrity.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at"
}

Retrieve and navigate agent records

Dive into the orchestration realm with the ability to list and paginate through HUMAN protocol agents. This endpoint empowers you to access detailed records of agents, filtering them by status and registration time, ensuring precise control over your data exploration.

Responses

Response samples

Content type
application/json

Retrieve a list of active agents with pagination.

{
  • "data": [
    ],
  • "limit": 2,
  • "next_cursor": "opaque_cursor_string"
}

Update organizational details securely

Refine the identity and configuration of your organization within the HUMAN ecosystem. This endpoint empowers administrators to update key organizational attributes, ensuring alignment with evolving goals and compliance requirements. By leveraging this capability, you can effortlessly manage organizational dynamics through cryptographic identity and secure task orchestration.

Request Body schema: application/json
required
name
string

The human-readable name of the organization.

slug
string

A unique identifier for the organization.

logo_url
string

URL to the organization's logo.

deployment_mode
string

Current mode of deployment, e.g., 'development' or 'production'.

data_residency_tier
string

Tier defining data residency restrictions.

data_residency_region
string

Region where data is stored.

autonomy_profile
string

Profile defining organizational autonomy level.

policies
object

Organizational policies in JSON format.

settings
object

Specific settings for organizational configuration.

Responses

Request samples

Content type
application/json

This example demonstrates a request to update the organization's name and switch its deployment mode to 'production'.

{
  • "name": "Acme Corp",
  • "deployment_mode": "production"
}

Response samples

Content type
application/json

The organization Acme Corp's details have been successfully updated.

{
  • "orgDid": "did:human:acme",
  • "name": "Acme Corp",
  • "slug": "acme-corp",
  • "logo_url": "https://example.com/logo.png",
  • "deployment_mode": "production",
  • "data_residency_tier": "premium",
  • "data_residency_region": "us-east-1",
  • "autonomy_profile": "advanced",
  • "policies": {
    },
  • "settings": {
    }
}

Retrieve paginated list of devices

Explore the vast network of devices under your organization's purview. This endpoint allows you to seamlessly paginate through enrolled devices, ensuring you stay on top of your technological landscape. Whether tracking IoT devices or managing enterprise hardware, maintain a clear view of your assets.

Responses

Response samples

Content type
application/json

A list of devices for the organization ACME Corp.

{
  • "data": [
    ],
  • "hasMore": false,
  • "limit": 2,
  • "nextCursor": "opaqueCursor123"
}

Register new device in control plane

Orchestrate the enrollment of a new device within your organization using HUMAN's control plane. Connect devices with the HUMAN network, track their capabilities, and ensure secure task routing with the power of AI. This endpoint is crucial for maintaining seamless operations across distributed systems.

Request Body schema: application/json
required
org_did
required
string

Decentralized identifier for the organization

device_did
string

Decentralized identifier for the device

label
required
string

Human-readable label for identifying the device

fingerprint
string

Unique fingerprint for device identification

device_type
string

Type of device, e.g., 'edge', 'cloud'

capabilities
object

Capabilities this device offers as a JSON object

metadata
object

Additional metadata about the device

Responses

Request samples

Content type
application/json

Enroll a device with essential information

{
  • "org_did": "did:example:123456789abcdefghi",
  • "device_did": "did:example:abcdefghij123456789",
  • "label": "Edge Device #42",
  • "fingerprint": "abc123fingerprint",
  • "device_type": "edge",
  • "capabilities": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "device-12345",
  • "org_did": "did:example:123456789abcdefghi",
  • "device_did": "did:example:abcdefghij123456789",
  • "label": "Edge Device #42",
  • "fingerprint": "abc123fingerprint",
  • "device_type": "edge",
  • "capabilities": {
    },
  • "metadata": {
    },
  • "enrolled_by": "passport-xyz123"
}

Retrieve organizational device topology

Dive into the intricate web of devices and their interconnections within an organization. This endpoint unveils the topology graph, a vivid map that helps administrators visualize and manage their digital ecosystem efficiently.

Responses

Response samples

Content type
application/json

Visual representation of Acme's interconnected devices.

{
  • "nodes": [
    ],
  • "edges": [
    ]
}

Retrieve Agent by Decentralized ID

Discover the unique capabilities and skills of a specific agent, identified by their cryptographic Passport. This endpoint is your gateway to understanding the role and history of an agent within the HUMAN ecosystem, offering insights into their past tasks and skillset.

Responses

Response samples

Content type
application/json

Details of an agent from ACME Corp known for processing complex invoices.

{
  • "agentDid": "did:human:123456789abcdefghi",
  • "name": "Invoice Processor 3000",
  • "capabilities": [
    ],
  • "lastActive": "2023-10-15T14:48:00Z"
}

Pause an Agent's Active Schedule

In the dynamic world of Human-AI collaboration, there are moments when pausing an agent's schedule becomes essential. This endpoint empowers you to momentarily halt the operations of an agent, ensuring flexibility and control over automated processes. Whether it's a strategic pause for maintenance or oversight, this endpoint is your tool for agile orchestration.

Responses

Response samples

Content type
application/json

The agent's schedule is paused successfully.

{
  • "agentDid": "did:example:acme-agent-123",
  • "status": "paused"
}

Resume a paused agent's operations

In the dynamic world of Human-AI collaboration, there's often a need to pause and resume activities as priorities shift. This endpoint breathes life back into a paused agent, enabling it to resume its tasks as part of a larger orchestration. By providing the agent's unique digital identity, you can seamlessly reactivate its capabilities within the HUMAN ecosystem.

Responses

Response samples

Content type
application/json
{
  • "agentDid": "did:example:1234567890",
  • "status": "active"
}

Override Agent Autonomy Settings

Empower your organization by customizing AI agent behaviors for specific tasks. This endpoint allows you to fine-tune the decision-making autonomy of an agent, ensuring it aligns with the unique operational needs of your organization.

Request Body schema: application/json
required
autonomy_level
required
string
Enum: "paranoid" "balanced" "aggressive"

The level of autonomy assigned to the agent.

org_did
required
string

The Decentralized Identifier (DID) of the organization setting the override.

reason
string

Optional rationale for setting or changing the autonomy level.

Responses

Request samples

Content type
application/json

Overrides the autonomy level of an agent handling invoice processing tasks to 'balanced' for the 'acme' organization.

{
  • "autonomy_level": "balanced",
  • "org_did": "org:acme",
  • "reason": "Ensuring proper oversight during financial audits."
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "org_did": "org:acme",
  • "agent_did": "agent:xyz123",
  • "autonomy_level": "balanced",
  • "set_by": "passport:alice",
  • "reason": "Ensuring proper oversight during financial audits.",
  • "updated_at": "2023-10-05T14:48:00.000Z"
}

Create and escalate incident for review

In the ever-evolving landscape of digital operations, the ability to swiftly identify and manage incidents is crucial. This endpoint empowers organizations to register new incidents, offering an opportunity for automatic escalation to human review if the incident's severity demands it. With a focus on both speed and accuracy, this API ensures that no critical event goes unnoticed, providing peace of mind and operational resilience.

Request Body schema: application/json
required
org_did
required
string

Decentralized Identifier (DID) of the organization

title
required
string

A brief title summarizing the incident

scan_id
string or null

Identifier for the scan that detected the incident

source_event_id
string or null

ID of the originating event triggering this incident

incident_type
string
Default: "anomaly"

Type classification of the incident

severity
string
Default: "medium"
Enum: "low" "medium" "high" "critical"

Severity level of the incident

description
string or null

Detailed description of the incident

object

Estimated impact scope of the incident

proposed_actions
Array of strings

List of actions proposed to mitigate the incident

object

Raw data associated with the incident

created_by_agent
string or null

Agent ID responsible for creating the incident

request_escalation
boolean
Default: false

Indicator whether manual escalation to human review is requested

skip_auto_escalation
boolean
Default: false

Flag to skip automatic escalation based on severity

Responses

Request samples

Content type
application/json

Registers an incident with minimal required fields

{
  • "org_did": "did:example:acme",
  • "title": "Unexpected spike in CPU usage",
  • "severity": "high",
  • "request_escalation": true
}

Response samples

Content type
application/json

The CPU usage spiked unexpectedly, potentially causing performance degradation.

null

Retrieve detailed incident information

Dive into the heart of incident management with this endpoint, which fetches not only the incident's core details but also a tapestry of linked approvals and external issues. By providing comprehensive insights into each incident, it empowers organizations to understand and resolve issues with precision and efficiency.

Responses

Response samples

Content type
application/json

An example response showing a complete incident with associated approval requests and external issues.

{
  • "id": "incident-12345",
  • "title": "Network Outage in Data Center",
  • "status": "Investigating",
  • "linked_approvals": [
    ],
  • "linked_external_issues": [],
  • "workbench_links": {
    }
}

Update and escalate incident status seamlessly

This endpoint breathes life into incident management by allowing seamless status updates and escalations for incidents. It ensures that your organization's response to incidents is swift, keeping security tight and operations smooth. Dive into the orchestration of human and AI with a single call.

Request Body schema: application/json
required
status
string
Enum: "open" "investigating" "escalated" "resolved" "dismissed"

The status to update the incident to.

severity
integer

The severity level of the incident.

resolution_notes
string

Notes detailing the resolution process, required if status is 'resolved' or 'dismissed'.

Responses

Request samples

Content type
application/json

Escalate an incident to human review with detailed notes.

{
  • "status": "escalated",
  • "resolution_notes": "Additional review required due to complexity."
}

Response samples

Content type
application/json

Marks the incident as resolved with notes.

{
  • "id": "inc_12345",
  • "status": "resolved",
  • "resolved_by": "passport_67890",
  • "resolved_at": "2023-10-12T07:20:50.52Z",
  • "resolution_notes": "Issue resolved after resetting the server."
}

Retrieve specific escalation details

Discover the current status of a particular escalation request within your workflow. This endpoint empowers agents and systems to track and manage critical escalations, ensuring timely and effective resolution. By understanding the journey of an escalation, teams can enhance their decision-making and responsiveness.

Responses

Response samples

Content type
application/json

A typical response when fetching an existing escalation

{
  • "id": "esc-12345",
  • "status": "pending",
  • "createdAt": "2023-10-11T14:32:00Z",
  • "updatedAt": "2023-10-12T09:15:00Z",
  • "details": "Awaiting approval from upper management"
}

Unenroll device from organization's control plane

Remove a device from the organization's orchestration network, cascading updates throughout the system. This endpoint ensures that devices no longer required or transferred are securely and thoroughly unenrolled, maintaining system integrity and security.

Responses

Response samples

Content type
application/json

The device with ID 12345 was successfully unenrolled from the organization with DID acme:org:9876.

null

Retrieve Available Extensions for Navigation

Discover the universe of extensions tailored to your organization's needs, filtered by navigation scope. This endpoint opens the door to a curated selection of tools, enhancing your organization's capabilities with precision.

Responses

Response samples

Content type
application/json

A user from the 'acme' organization retrieves extensions related to the 'companion_panel' navigation scope.

{
  • "extensions": [
    ]
}

Ontology

Retrieve curated ontology package list

Discover the universe of capabilities with this endpoint, which fetches a curated list of ontology packages. Ideal for developers and organizations aiming to leverage the HUMAN Protocol's power, it helps you navigate through the capabilities landscape by filtering packages by scope, publisher, and status.

Responses

Response samples

Content type
application/json

Retrieve a list of published ontology packages for acme organization.

{
  • "packages": [
    ],
  • "count": 1
}

Publish a new ontology package

In the vibrant world of Human-AI collaboration, the tools we utilize must evolve. This endpoint allows you to publish a new ontology package, a cornerstone for skill tracking and capability management. By enabling organizations to define and share their ontology structures, it fosters a rich ecosystem of knowledge and collaboration.

Request Body schema: application/json
required
id
required
string

Unique identifier for the ontology package.

version
required
string

Semantic versioning of the package.

publisher_name
required
string

Name of the publisher.

name
required
string

Name of the ontology package.

signature
required
string

Cryptographic signature of the package.

manifest_json
required
object

JSON object detailing the package manifest.

scope
required
string
Enum: "canonical" "org"

Scope of the package.

license
required
string
Enum: "open" "commercial" "proprietary"

License type for the package.

org_slug
string

Organization slug when scope is 'org'.

description
string

Optional description of the package.

changelog
string

Optional changelog for the package.

price_amount
number

Price amount for the package.

price_currency
string

Currency for the price.

price_billing_period
string
Enum: "one-time" "annual" "monthly"

Billing period for the price.

Responses

Request samples

Content type
application/json

Publishing a new ontology package for Acme Corp.

{
  • "id": "acme-ontology-v1",
  • "version": "1.0.0",
  • "publisher_name": "Acme Corp",
  • "name": "Acme Ontology",
  • "signature": "a1b2c3signature",
  • "manifest_json": {
    },
  • "scope": "org",
  • "license": "commercial",
  • "org_slug": "acme",
  • "description": "Ontology package for processing and modeling data.",
  • "changelog": "Initial release.",
  • "price_amount": 199.99,
  • "price_currency": "USD",
  • "price_billing_period": "annual"
}

Response samples

Content type
application/json
{
  • "id": "acme-ontology-v1",
  • "version": "1.0.0",
  • "name": "Acme Ontology",
  • "scope": "org",
  • "license": "commercial",
  • "status": "published",
  • "publisher": {
    },
  • "capability_count": 2,
  • "created_at": "2023-10-04T00:00:00Z",
  • "published_at": "2023-10-04T00:00:00Z"
}

Retrieve ontology package metadata

Uncover the complete lineage and evolution of an ontology package with this endpoint. It provides a detailed account of all versions of a specified package, allowing users to trace its history and understand its development over time. This is crucial for tracking capability changes and ensuring compliance with evolving standards.

Responses

Response samples

Content type
application/json

Retrieve detailed metadata for the 'acme' organization's package with all versions.

{
  • "id": "pkg_12345",
  • "version_count": 3,
  • "name": "Acme Invoice Ontology",
  • "description": "An ontology package for processing invoices in the Acme organization.",
  • "publisher": {
    },
  • "scope": "invoices",
  • "license": "MIT",
  • "versions": [
    ]
}

Retrieve Ontology Package Details

Delve into the rich tapestry of skills and capabilities with our ontology packages. This endpoint grants you access to the intricate details of a specific ontology package version, including its publisher, licensing, and capabilities. Ideal for orchestrating human expertise and AI synergy.

Responses

Response samples

Content type
application/json

Retrieving details for an active ontology package used by Acme Corp.

{
  • "id": "pkg_001",
  • "version": "1.0.3",
  • "publisher": {
    },
  • "name": "Invoice Processing Ontology",
  • "description": "A comprehensive package for processing invoices with AI assistance.",
  • "scope": "Finance",
  • "license": "MIT",
  • "pricing": {
    },
  • "capability_count": 10,
  • "status": "active",
  • "changelog": "Added new capabilities for multi-currency support.",
  • "created_at": "2023-01-15T08:00:00Z",
  • "published_at": "2023-02-10T09:30:00Z"
}

Retrieve ontologies for an organization

Explore the semantic fabric of your organization by retrieving a list of ontologies. These ontologies, intricately woven by the hands of knowledge engineers, serve as the backbone for task orchestration and AI empowerment within your organization. Discover which ontologies are active and who initiated their installation.

Responses

Response samples

Content type
application/json

Fetching active ontologies for Acme Corp.

{
  • "org_id": "acme-corp",
  • "installations": [
    ],
  • "count": 1
}

Retrieve Ontology Package Manifest

Delve into the intricate details of an ontology package with its complete manifest and cryptographic signature. This endpoint empowers users to explore the capabilities within a package while ensuring secure and authorized access through HUMAN's robust identity protocols.

Responses

Response samples

Content type
application/json

Retrieve the manifest of the 'acme' organization's latest published ontology package.

{
  • "id": "acme-invoice-processing",
  • "version": "1.2.3",
  • "name": "Invoice Processing with AI",
  • "license": "open",
  • "status": "published",
  • "publisher": {
    },
  • "signature": "MEUCIQD1z...",
  • "manifest_json": {
    },
  • "published_at": "2023-10-11T12:00:00Z"
}

Install an Ontology Package for Organization

This endpoint allows organizations to seamlessly install or update ontology packages within the HUMAN platform. By ensuring only published package versions are used, it maintains integrity and provides a record of installation activities, helping organizations stay on top of their capabilities.

Request Body schema: application/json
required
org_id
required
string

Unique identifier for the organization.

org_slug
required
string

Slug name for the organization.

package_version
required
string

The version of the ontology package to install, must be a semantic version.

payment_id
string

Optional payment identifier if payment processing is involved.

Responses

Request samples

Content type
application/json

This example demonstrates installing version 1.2.3 of a package for ACME Corporation.

{
  • "org_id": "org-12345",
  • "org_slug": "acme-corp",
  • "package_version": "1.2.3",
  • "payment_id": "pay-6789"
}

Response samples

Content type
application/json
{
  • "installation_id": "ont_inst_001",
  • "package_id": "pkg-123",
  • "package_version": "1.2.3",
  • "org_id": "org-12345",
  • "org_slug": "acme-corp",
  • "status": "active",
  • "installed_by": "user-789",
  • "installed_at": "2023-10-01T12:00:00Z",
  • "updated": true
}

Search capability ontology

Dive into the depths of HUMAN's Capability Graph with this endpoint, crafted to unearth the skills and attributes hidden within our ontology. Whether you're matching precise skills or exploring broader categories, this search tool is your gateway to understanding and utilizing HUMAN's rich skill taxonomy.

Responses

Response samples

Content type
application/json

A search for 'invoice processing' in the ontology.

{
  • "results": [
    ],
  • "total": 1,
  • "query_embedding_cached": false
}

Retrieve canonical capability details

In the intricate dance of human and AI collaboration, understanding the core capabilities is paramount. This endpoint reveals the canonical form of an organizational capability, ensuring clarity and consistency across the HUMAN ecosystem. By resolving to a canonical URI, it provides a solid reference point in the ever-evolving capability graph.

Responses

Response samples

Content type
application/json
{
  • "canonicalUri": "capability://acme/finance/invoice-processing",
  • "description": "Processes financial invoices for Acme Corp."
}

Propose updates to a capability ontology

Engage with the HUMAN protocol by proposing canonical updates to a capability. This endpoint empowers users to enhance the system's understanding of a skill, ensuring the AI aligns closer with human expertise.

Request Body schema: application/json
required
name
required
string

The new name for the capability.

description
required
string

A detailed explanation of the capability's function.

attributes
Array of strings

List of attributes that define the capability.

Responses

Request samples

Content type
application/json

Propose a new name and description for a capability.

{
  • "name": "Advanced Image Analysis",
  • "description": "A capability for processing and interpreting complex image data.",
  • "attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Proposal submitted successfully."
}

Promote capability to canonical status

Elevate an organizational capability to a canonical status, ensuring it becomes a recognized skill within the HUMAN ecosystem. This endpoint fosters standardization and interoperability by allowing organizations to formalize their unique skills for broader use.

Request Body schema: application/json
required
canonical_uri
required
string

The URI that uniquely identifies the canonical form of the capability.

promoter_did
required
string

DID of the agent promoting the capability.

Responses

Request samples

Content type
application/json

An example of promoting the InvoiceProcessing capability to canonical, with a specific URI and promoter DID.

{
  • "canonical_uri": "capability://acme/invoice-processing",
  • "promoter_did": "did:example:123456789abcdefghi"
}

Response samples

Content type
application/json
{
  • "org_cap_id": "cap_67890",
  • "status": "promoted",
  • "canonical_uri": "capability://acme/invoice-processing",
  • "deprecated_org_uri": "org://acme/legacy-invoice-processing",
  • "provenance_event_id": "pe_1697043000000"
}

Retrieve detailed capability ontology

Delve into the intricacies of a specific capability within the HUMAN ecosystem. This endpoint reveals the nuanced relationships and metadata that define a capability, providing a comprehensive view of its role and market dynamics. It's the key to unlocking how capabilities interconnect and evolve in response to market demands.

Responses

Response samples

Content type
application/json

An example highlighting a capability used by Acme Corp to enhance AI negotiation skills.

{
  • "id": "cap_ai_negotiation",
  • "canonical_name": "AI Negotiation",
  • "category": "AI Skills",
  • "subcategory": "Negotiation",
  • "domain": "Artificial Intelligence",
  • "description": "Enables AI systems to effectively negotiate agreements.",
  • "relationships": [
    ],
  • "metadata": {
    }
}

Retrieve available ontology packages

Dive into the world of HUMAN's ontology packages, where AI capabilities are meticulously organized and tracked. This endpoint offers a window into the published skill sets, empowering you to explore, evaluate, and integrate them seamlessly into your workflow.

Responses

Response samples

Content type
application/json

Fetching a list of ontology packages published by Acme Corp.

{
  • "packages": [
    ],
  • "count": 1
}

Packages

Retrieve curated ontology package list

Discover the universe of capabilities with this endpoint, which fetches a curated list of ontology packages. Ideal for developers and organizations aiming to leverage the HUMAN Protocol's power, it helps you navigate through the capabilities landscape by filtering packages by scope, publisher, and status.

Responses

Response samples

Content type
application/json

Retrieve a list of published ontology packages for acme organization.

{
  • "packages": [
    ],
  • "count": 1
}

Retrieve ontology package metadata

Uncover the complete lineage and evolution of an ontology package with this endpoint. It provides a detailed account of all versions of a specified package, allowing users to trace its history and understand its development over time. This is crucial for tracking capability changes and ensuring compliance with evolving standards.

Responses

Response samples

Content type
application/json

Retrieve detailed metadata for the 'acme' organization's package with all versions.

{
  • "id": "pkg_12345",
  • "version_count": 3,
  • "name": "Acme Invoice Ontology",
  • "description": "An ontology package for processing invoices in the Acme organization.",
  • "publisher": {
    },
  • "scope": "invoices",
  • "license": "MIT",
  • "versions": [
    ]
}

Retrieve Ontology Package Details

Delve into the rich tapestry of skills and capabilities with our ontology packages. This endpoint grants you access to the intricate details of a specific ontology package version, including its publisher, licensing, and capabilities. Ideal for orchestrating human expertise and AI synergy.

Responses

Response samples

Content type
application/json

Retrieving details for an active ontology package used by Acme Corp.

{
  • "id": "pkg_001",
  • "version": "1.0.3",
  • "publisher": {
    },
  • "name": "Invoice Processing Ontology",
  • "description": "A comprehensive package for processing invoices with AI assistance.",
  • "scope": "Finance",
  • "license": "MIT",
  • "pricing": {
    },
  • "capability_count": 10,
  • "status": "active",
  • "changelog": "Added new capabilities for multi-currency support.",
  • "created_at": "2023-01-15T08:00:00Z",
  • "published_at": "2023-02-10T09:30:00Z"
}

Retrieve Ontology Package Manifest

Delve into the intricate details of an ontology package with its complete manifest and cryptographic signature. This endpoint empowers users to explore the capabilities within a package while ensuring secure and authorized access through HUMAN's robust identity protocols.

Responses

Response samples

Content type
application/json

Retrieve the manifest of the 'acme' organization's latest published ontology package.

{
  • "id": "acme-invoice-processing",
  • "version": "1.2.3",
  • "name": "Invoice Processing with AI",
  • "license": "open",
  • "status": "published",
  • "publisher": {
    },
  • "signature": "MEUCIQD1z...",
  • "manifest_json": {
    },
  • "published_at": "2023-10-11T12:00:00Z"
}

Retrieve specific capability package version

Delve into the rich tapestry of skills by fetching a specific version of a capability package. This endpoint is your gateway to understanding the evolution and offerings of a package within the HUMAN ecosystem, providing both provenance and potential.

Responses

Response samples

Content type
application/json

Retrieving the 'acme-invoice-processor' package version 1.2.0

{
  • "id": "acme-invoice-processor",
  • "version": "1.2.0",
  • "publisher": {
    },
  • "name": "Invoice Processor",
  • "description": "A powerful tool for processing and automating invoice workflows.",
  • "scope": "enterprise",
  • "license": "MIT",
  • "pricing": {
    },
  • "capability_count": 15,
  • "status": "active",
  • "changelog": "Added new OCR feature for faster invoice scanning.",
  • "created_at": "2023-08-10T14:48:00Z",
  • "published_at": "2023-09-01T10:00:00Z"
}

Capability Graph

Publish a new ontology package

In the vibrant world of Human-AI collaboration, the tools we utilize must evolve. This endpoint allows you to publish a new ontology package, a cornerstone for skill tracking and capability management. By enabling organizations to define and share their ontology structures, it fosters a rich ecosystem of knowledge and collaboration.

Request Body schema: application/json
required
id
required
string

Unique identifier for the ontology package.

version
required
string

Semantic versioning of the package.

publisher_name
required
string

Name of the publisher.

name
required
string

Name of the ontology package.

signature
required
string

Cryptographic signature of the package.

manifest_json
required
object

JSON object detailing the package manifest.

scope
required
string
Enum: "canonical" "org"

Scope of the package.

license
required
string
Enum: "open" "commercial" "proprietary"

License type for the package.

org_slug
string

Organization slug when scope is 'org'.

description
string

Optional description of the package.

changelog
string

Optional changelog for the package.

price_amount
number

Price amount for the package.

price_currency
string

Currency for the price.

price_billing_period
string
Enum: "one-time" "annual" "monthly"

Billing period for the price.

Responses

Request samples

Content type
application/json

Publishing a new ontology package for Acme Corp.

{
  • "id": "acme-ontology-v1",
  • "version": "1.0.0",
  • "publisher_name": "Acme Corp",
  • "name": "Acme Ontology",
  • "signature": "a1b2c3signature",
  • "manifest_json": {
    },
  • "scope": "org",
  • "license": "commercial",
  • "org_slug": "acme",
  • "description": "Ontology package for processing and modeling data.",
  • "changelog": "Initial release.",
  • "price_amount": 199.99,
  • "price_currency": "USD",
  • "price_billing_period": "annual"
}

Response samples

Content type
application/json
{
  • "id": "acme-ontology-v1",
  • "version": "1.0.0",
  • "name": "Acme Ontology",
  • "scope": "org",
  • "license": "commercial",
  • "status": "published",
  • "publisher": {
    },
  • "capability_count": 2,
  • "created_at": "2023-10-04T00:00:00Z",
  • "published_at": "2023-10-04T00:00:00Z"
}

Record evidence for capability grant

Submit evidence to validate a capability grant in the HUMAN ecosystem. This endpoint empowers organizations to substantiate their skill claims with trusted data, ensuring integrity in a collaborative workflow.

Request Body schema: application/json
required
passport_did
required
string

The decentralized identifier (DID) of the passport.

capability_id
required
string

Identifier of the capability being evidenced.

required
object

Responses

Request samples

Content type
application/json

Submits evidence for a skill grant with manual verification.

{
  • "passport_did": "did:human:123456789abcdefghi",
  • "capability_id": "capability://acme/coding",
  • "evidence": {}
}

Response samples

Content type
application/json
{
  • "grant_id": "cgev_987654321abcdefghi",
  • "passport_did": "did:human:123456789abcdefghi",
  • "capability_id": "capability://acme/coding",
  • "status": "active",
  • "recorded_at": "2023-10-12T07:20:50.52Z"
}

Remove a Capability Grant by ID

This endpoint allows you to delete a specific capability grant from the Capability Graph, effectively revoking a granted skill or permission. It's like removing a key from a keyring, ensuring that access is only available to those who truly need it, enhancing security and clarity in your orchestrated operations.

Responses

Response samples

Content type
application/json

Indicates successful removal of the capability grant.

{
  • "message": "Capability grant successfully deleted."
}

Organization

Retrieve ontologies for an organization

Explore the semantic fabric of your organization by retrieving a list of ontologies. These ontologies, intricately woven by the hands of knowledge engineers, serve as the backbone for task orchestration and AI empowerment within your organization. Discover which ontologies are active and who initiated their installation.

Responses

Response samples

Content type
application/json

Fetching active ontologies for Acme Corp.

{
  • "org_id": "acme-corp",
  • "installations": [
    ],
  • "count": 1
}

Fetch organizational event logs

Delve into the chronicles of your organization with this endpoint, designed to retrieve a curated list of events. Whether you're tracking the past or steering towards your future, understanding your events is crucial for strategic decision-making.

Responses

Response samples

Content type
application/json

Retrieve the latest 10 events for Acme Corp, revealing recent interactions and changes.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursor": "2023-10-03T14:48:00.000Z",
  • "hasMore": false
}

Retrieve paginated list of organization members

Discover who is part of your organization with this endpoint. It serves as a gateway to explore the human network within an organization, empowering you to manage and collaborate with your members effectively. This endpoint ensures that only authorized users can access information, maintaining privacy and data integrity.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "joined_at"
}

Add member to organization

Empower your organization's growth by adding new members who bring diverse skills and expertise. This endpoint allows you to expand your team by securely adding individuals to your organization, ensuring that only authorized personnel can perform this task.

Request Body schema: application/json
required
human_did
required
string

The Passport DID of the human being added

role
required
string

The role assigned to the new member within the organization

Responses

Request samples

Content type
application/json

This example demonstrates adding a new member as a Senior Engineer to the organization.

{
  • "human_did": "did:human:123456",
  • "role": "senior_engineer"
}

Response samples

Content type
application/json
{
  • "org_did": "did:org:acme",
  • "human_did": "did:human:123456",
  • "work_agent_did": "did:agent:123456-work-acme",
  • "role": "senior_engineer",
  • "joined_at": "2023-10-05T14:48:00.000Z",
  • "terminated_at": null,
  • "terminated_by": null,
  • "termination_reason": null
}

Terminate a member's employment

In the intricate ballet of organizational management, there comes a time when a member must exit the stage. This endpoint gracefully orchestrates the termination of a member's employment within the HUMAN platform, ensuring proper documentation and provenance. It exists to maintain order and clarity in the dynamic interplay between human and AI roles.

Request Body schema: application/json
required
reason
string

A brief explanation for the termination

Responses

Request samples

Content type
application/json

Provides a reason for the member's termination

{
  • "reason": "Position redundancy due to restructuring"
}

Response samples

Content type
application/json
{
  • "org_did": "did:org:acme",
  • "human_did": "did:human:john_doe",
  • "work_agent_did": "did:agent:agent123",
  • "role": "Software Engineer",
  • "joined_at": "2022-01-15T08:00:00Z",
  • "terminated_at": "2023-10-10T09:00:00Z",
  • "terminated_by": "did:agent:manager456",
  • "termination_reason": "Position redundancy due to restructuring"
}

Retrieve an organization's profile information

Explore the digital tapestry of an organization’s identity with this endpoint. It unveils the public profile of an organization, including its unique cryptographic identity (DID), branding elements, and provenance data. This ensures transparency and trust in interactions, vital for seamless Human-AI collaboration.

Responses

Response samples

Content type
application/json

Retrieving the profile for the fictional Acme Corporation.

{
  • "org_did": "did:example:acme123",
  • "display_name": "Acme Corporation",
  • "description": "Leading provider of innovative solutions.",
  • "website_url": "https://www.acme.com",
  • "logo_url": "https://www.acme.com/logo.png",
  • "brand_tokens": "acme2023",
  • "updated_by": "did:example:agent456",
  • "created_at": "2023-01-15T08:00:00Z",
  • "updated_at": "2023-10-05T12:00:00Z"
}

Update Organization Profile Details

This endpoint empowers organizations to maintain accurate and up-to-date profiles by allowing authenticated updates to their profile details. It ensures that only the rightful owner of the organization can modify its profile, safeguarding against unauthorized changes.

Request Body schema: application/json
required
Any of
display_name
required
string <= 255 characters
description
string or null
website_url
string or null
logo_url
string or null
brand_tokens
object or null

Responses

Request samples

Content type
application/json

This example demonstrates updating the display name of an organization.

{
  • "display_name": "Acme Corporation"
}

Response samples

Content type
application/json
{
  • "org_did": "did:example:123456789abcdefghi",
  • "display_name": "Acme Corporation",
  • "description": "Innovator in industry solutions",
  • "website_url": "https://acme.example.com",
  • "logo_url": "https://acme.example.com/logo.png",
  • "brand_tokens": {
    },
  • "updated_by": "did:example:agent12345",
  • "created_at": "2023-01-01T12:00:00Z",
  • "updated_at": "2023-10-01T12:00:00Z"
}

Retrieve organization's secret keys

Embark on a journey through the vault of secrets tailored for your organization. This endpoint is your key to uncovering cryptographic treasures, filtered by an optional prefix to hone in on specific secrets. Whether you're securing data or managing credentials, this is an essential tool for orchestrating human-AI interactions with precision.

Responses

Response samples

Content type
application/json

Organization retrieves secret key names to audit credentials.

{
  • "keys": [
    ]
}

Retrieve list of organization employees

Discover the diverse talent within your organization by listing all current employees. This endpoint empowers you with the ability to manage workforce data efficiently, ensuring you can make informed decisions quickly. It's a key tool for organizations like 'acme' to maintain a dynamic understanding of their human resources landscape.

Responses

Response samples

Content type
application/json

A snapshot of the employee directory for Acme Corp, showcasing a diverse set of roles and departments.

{
  • "data": [
    ],
  • "limit": 50,
  • "cursorField": "created_at"
}

Register a unique organization slug

Organizations claim a globally unique slug, essential for agent URI addressing, ensuring seamless namespace resolution in the HUMAN ecosystem. This process fortifies your organization's identity, carving a distinct digital path with every agent interaction.

Request Body schema: application/json
required
slug
required
string

The desired slug, must be 3-64 characters, lowercase alphanumeric with hyphens, starting and ending with an alphanumeric character.

display_name
string

Optional human-readable name for the organization.

Responses

Request samples

Content type
application/json

Claim a slug for Acme Corporation's namespace

{
  • "slug": "acme-corp",
  • "display_name": "Acme Corporation"
}

Response samples

Content type
application/json
null

Retrieve organization's slug if claimed

Discover the unique and memorable slug associated with an organization, revealing its digital identity on the HUMAN platform. This endpoint addresses the need for distinct identification, ensuring seamless interaction and recognition in a distributed, AI-driven ecosystem.

Responses

Response samples

Content type
application/json

Fetching the slug for 'acme-corp'.

{
  • "slug": "acme-corp",
  • "org_did": "did:human:example123",
  • "display_name": "Acme Corporation",
  • "claimed_at": "2023-10-05T14:48:00.000Z"
}

Soft-delete an organization's muscle

This endpoint allows organizations to gracefully retire skills, known as 'muscles', by marking them as 'uninstalled'. This mechanism ensures a clean audit trail while preserving historical data, enabling organizations to maintain transparency and compliance.

Responses

Response samples

Content type
application/json

An example where the muscle is successfully uninstalled.

{
  • "status": "uninstalled",
  • "muscle_id": "muscle-abc123"
}

Retrieve organization details by DID

Delve into the heart of HUMAN's orchestration by fetching the details of an organization using its Decentralized Identifier (DID). This endpoint empowers you to access essential data that defines an organization’s identity within the HUMAN network, ensuring seamless integration and interaction.

Responses

Response samples

Content type
application/json
{
  • "orgDid": "did:human:123456789abcdefghi",
  • "name": "Acme Corporation",
  • "createdAt": "2023-10-01T12:34:56Z"
}

Create or Update Organization Policy

Orchestrate your organization's operations with precision by defining or updating policies. This endpoint enables organizations to enforce rules that govern their conduct within the HUMAN network, ensuring alignment with strategic goals and regulatory requirements.

Request Body schema: application/json
required
policy_type
required
string
Enum: "marketplace" "agent_autonomy_domain" "audit_retention" "data_residency" "transparency_redaction"

The type of policy to apply.

policy_rules
required
object

The rules defining the policy. Specific structure depends on the policy_type.

Responses

Request samples

Content type
application/json

An example of creating a marketplace policy.

{
  • "policy_type": "marketplace",
  • "policy_rules": {
    }
}

Response samples

Content type
application/json
null

Retrieve organization policies list

Dive into the strategic framework of an organization by retrieving its policies. This endpoint allows you to access the structured set of rules and guidelines that govern an organization identified by its DID. It's a window into understanding how the organization orchestrates its operations.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Configure Organization Compute Policy

Empower your organization by setting a compute policy that aligns with your operational needs, either opting for self-hosted resources or leveraging HUMAN's infrastructure. This decision impacts cost management and resource allocation, ensuring flexibility and control over computational expenses.

Request Body schema: application/json
required
compute_mode
string
Enum: "BYOK" "HUMAN_HOSTED"
object

Responses

Request samples

Content type
application/json

An organization opting for HUMAN-hosted compute with specified spend limits.

{
  • "compute_mode": "HUMAN_HOSTED",
  • "compute_policy": {
    }
}

Response samples

Content type
application/json
null

Create a new workforce queue

In a dynamic organization, managing tasks efficiently is key. This endpoint allows you to create a new queue within your organization's workforce, ensuring that tasks are routed effectively to the right personnel. By defining task types and worker capabilities, you tailor the flow to meet your operational demands.

Request Body schema: application/json
required
name
required
string

The name of the queue

description
string

A brief description of the queue

task_types
Array of strings

List of task types assigned to this queue

worker_ids
Array of strings

Identifiers of workers eligible for this queue

capability_filter
object

Criteria to filter workers based on capabilities

visibility
string
Enum: "internal_only" "public"

Visibility status of the queue

Responses

Request samples

Content type
application/json

Demonstrates creating a queue for handling customer support tasks

{
  • "name": "Customer Support",
  • "description": "Handles all incoming customer queries",
  • "task_types": [
    ],
  • "worker_ids": [
    ],
  • "capability_filter": {
    },
  • "visibility": "internal_only"
}

Response samples

Content type
application/json
{
  • "queue_id": "queue789",
  • "org_id": "acme",
  • "name": "Customer Support",
  • "description": "Handles all incoming customer queries",
  • "task_types": [
    ],
  • "worker_ids": [
    ],
  • "capability_filter": {
    },
  • "visibility": "internal_only"
}

Retrieve workforce workers by organization

Dive into the dynamic world of workforce management by fetching a curated list of workers associated with your organization. This endpoint empowers you to filter workers by status and paginate results, ensuring you always have the right people at your fingertips for an efficient operation.

Responses

Response samples

Content type
application/json

Fetching workers for the 'acme' organization with 2 active assignments.

{
  • "data": [
    ],
  • "hasMore": false,
  • "limit": 10,
  • "cursorField": "created_at"
}

Update a worker's profile in an organization

Modify the attributes of a worker within your organization, seamlessly aligning skills and roles. This endpoint empowers organizations to dynamically adapt their workforce capabilities in response to evolving needs, ensuring optimal efficiency and productivity.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve Organization Workforce Routing Config

Explore the intricate orchestration of human and AI collaboration within an organization. This endpoint unveils the current routing configuration, vital for ensuring tasks are allocated efficiently and safely. It's your window into the dynamic core of HumanOS task routing.

Responses

Response samples

Content type
application/json

Example of a successful retrieval of routing configuration for an organization.

{
  • "org_did": "did:human:acme",
  • "config": {
    },
  • "updated_at": "2023-10-01T12:34:56Z"
}

Install an Extension for an Organization

Empower your organization by seamlessly integrating new capabilities through extensible modules. This endpoint is the gateway to enhancing your operational landscape by installing extensions that align with your strategic goals.

Request Body schema: application/json
required
extensionId
required
string

Unique identifier of the extension to be installed.

config
object

Optional configuration settings for the extension.

Responses

Request samples

Content type
application/json

Installing the 'invoice-processor' extension with default settings.

{
  • "extensionId": "invoice-processor",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "inst_1234567890abcdef",
  • "entity_id": "org_acme_corp",
  • "extension_id": "invoice-processor",
  • "permissions": [ ],
  • "config": {
    },
  • "status": "active",
  • "triggers": null,
  • "installed_at": "2023-10-05T14:48:00Z",
  • "updated_at": "2023-10-05T14:48:00Z"
}

Retrieve installed extensions for organization

Unlock the potential of your organization by exploring the array of extensions currently installed. This endpoint offers a curated view into your toolkit, empowering you to harness the full spectrum of capabilities tailored to your needs. By understanding what's active, you can strategize your next innovations and streamline operations.

Responses

Response samples

Content type
application/json

Shows a typical response with two installed extensions.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": false
}

Retrieve organization-specific workflow details

Explore the dynamic landscape of your organization's workflows with this endpoint. It offers a window into the lifecycle, scope, and status of active workflows, empowering you to oversee and optimize your processes with precision.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 2,
  • "hasMore": true,
  • "cursorField": "updated_at"
}

Promote workflow scope within an organization

Elevate the scope of a workflow from a personal level to a broader organizational level, ensuring essential workflows gain the visibility they deserve. This endpoint empowers administrators to streamline operations by adjusting workflow accessibility and visibility across different levels of the organization.

Request Body schema: application/json
required
scope
required
string
Enum: "personal" "workspace" "org"

The target scope to promote the workflow to: personal, workspace, or org

Responses

Request samples

Content type
application/json

Illustrates changing a workflow's scope from personal to organizational level.

{
  • "scope": "org"
}

Response samples

Content type
application/json
{
  • "id": "wf123",
  • "scope": "org",
  • "updated_at": "2023-10-05T14:48:00Z"
}

Retrieve active muscles for organization

Explore the vibrant ecosystem of skills, known as 'muscles', installed in your organization’s HUMAN platform. This endpoint is your gateway to discovering the active tools your team has harnessed, ensuring seamless task orchestration and AI collaboration.

Responses

Response samples

Content type
application/json

Acme Corp retrieves a list of their active marketplace muscles.

{
  • "data": [
    ]
}

Disconnect a connector for an organization

In the HUMAN ecosystem, managing your connector's lifecycle is crucial for maintaining operational integrity. This endpoint allows organizations to disconnect a specific connector, ensuring security by revoking access and updating the connector's status. It's a vital tool for organizations aiming to maintain a secure and up-to-date environment.

Request Body schema: application/json
required
revoke_tokens
boolean

Indicate if tokens should be revoked during the disconnect process

Responses

Request samples

Content type
application/json

Demonstrates disconnecting a connector and revoking its tokens

{
  • "revoke_tokens": true
}

Response samples

Content type
application/json
{
  • "disconnected": true
}

Link Passport to Organization

In the world of HUMAN, identities are not just cryptographic tokens; they are passports to new opportunities. This endpoint links a user's cryptographic identity to their organizational role, ensuring that the right skills and capabilities are attributed to the right person. It's a vital step in creating a seamless Human-AI collaboration environment.

Request Body schema: application/json
required
linkingCode
required
string

A unique code provided by the organization to link the passport.

email
required
string <email>

The email address associated with the passport holder's organizational role.

Responses

Request samples

Content type
application/json

A request to link a passport with a valid linking code and email.

{
  • "linkingCode": "abc123-orglink",
  • "email": "john.doe@acme.org"
}

Response samples

Content type
application/json
{
  • "message": "Verification code sent to email",
  • "email": "john.doe@acme.org"
}

Retrieve founders of an organization passport

Behind every successful organization is a team of founders whose vision shapes its identity. This endpoint allows you to explore the individuals who established a given organization, identified by its decentralized identifier (DID). By understanding who these founders are, you gain insight into the organization's origin story and governance structure.

Responses

Response samples

Content type
application/json

Example showing the retrieval of founders for the organization 'acme'

{
  • "org_did": "did:org:acme",
  • "legal_name": "Acme Corp",
  • "status": "active",
  • "founders": [
    ],
  • "founder_count": 2
}

Upgrade organization governance tier

Empower your organization to unlock new capabilities by upgrading its governance tier. This endpoint validates your organization’s readiness and executes a tier upgrade, ensuring compliance and integrity through rigorous checks. Elevate your organization's potential while maintaining transparency and security.

Request Body schema: application/json
required
One of
requested_by
required
string

DID of the founder requesting the upgrade

target_tier
required
integer
Enum: 1 2 3

The desired governance tier

Responses

Request samples

Content type
application/json

Upgrade an organization to Tier 2 with valid founder DID

{
  • "requested_by": "did:human:abc123",
  • "target_tier": 2
}

Response samples

Content type
application/json
{
  • "org_did": "did:human:org456",
  • "previous_tier": 1,
  • "governance_tier": 2,
  • "founder_count": 3,
  • "provenance_id": "prov_789"
}

Dissolve an organizational passport

This endpoint initiates the irreversible dissolution of an organization's passport, signaling the end of its active status. By doing so, it ensures that all active agent delegations are revoked, safeguarding the integrity of the system. Whether asynchronously proposed for quorum approval or executed synchronously with signatures, this process is critical to maintaining a secure and trustworthy Human-AI orchestration.

Request Body schema: application/json
required
proposed_by
required
string^did:human:.*$

The DID of the proposing founder.

mode
string
Default: "async"
Enum: "async" "synchronous"

Mode of dissolution; defaults to async requiring quorum approval.

Array of objects

Required for synchronous mode. An array of cryptographic signatures from founders.

reason
string

Optional reason for dissolution proposal.

signature
string

Optional initial founder signature for async proposal.

Responses

Request samples

Content type
application/json
Example

Creating a dissolution proposal asynchronously with a reason.

{
  • "proposed_by": "did:human:12345",
  • "mode": "async",
  • "reason": "Strategic shift in organizational focus."
}

Response samples

Content type
application/json
{
  • "org_did": "did:human:org123",
  • "status": "dissolved",
  • "agents_revoked": 15,
  • "provenance_id": "prov_abc123",
  • "dissolved_at": "2023-11-01T12:34:56Z"
}

Retrieve Intent Briefs for an Organization

Delve into the orchestration of Human-AI collaboration by fetching intent briefs that guide AI interactions. This endpoint is crucial for organizations looking to monitor and enhance AI-driven workflows, by providing insights derived from the Capability Graph.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Retrieve organizational preference defaults

Discover the foundational preferences that guide your organization's operations within the HUMAN platform. This endpoint reveals the default settings, ensuring that your orchestration processes are aligned and consistent. It's crucial for maintaining a seamless integration of AI and human workflows.

Responses

Response samples

Content type
application/json

Example of Acme Corp's default preferences for task routing.

{
  • "org_did": "did:human:org:acme",
  • "preferences": {
    }
}

Update organization default preferences

This endpoint allows organizations to customize their AI companion's interaction style by setting default preferences. Tailor the formality, humor, and verbosity to ensure the AI aligns with your company's culture and communication norms.

Request Body schema: application/json
required
enforce_formality
string or null

The level of formality to enforce.

enforce_humor_off
boolean or null

Whether to enforce humor to be off.

enforce_language
string or null

The language to enforce for communications.

default_formality
string or null

The default formality level for interactions.

default_humor_level
string or null

The default humor level to apply.

default_verbosity
string or null

The default verbosity of responses.

org_instructions
string or null

Custom instructions specific to the organization.

Responses

Request samples

Content type
application/json

This example sets a formal communication style with no humor and English language.

{
  • "enforce_formality": "formal",
  • "enforce_humor_off": true,
  • "enforce_language": "en",
  • "default_formality": "formal",
  • "default_humor_level": null,
  • "default_verbosity": "concise",
  • "org_instructions": "Always use formal greetings."
}

Response samples

Content type
application/json

The response after successfully updating preferences.

{
  • "enforce_formality": "formal",
  • "enforce_humor_off": true,
  • "enforce_language": "en",
  • "default_formality": "formal",
  • "default_humor_level": null,
  • "default_verbosity": "concise",
  • "org_instructions": "Always use formal greetings."
}

Security

Create a delegation token for access control

In the intricate dance of human and AI collaboration, the Delegation Token is your backstage pass. It empowers entities to act on behalf of others, streamlining operations without sacrificing security. This endpoint creates a token, ensuring trusted interactions across the HUMAN platform.

Request Body schema: application/json
required
delegate
required
string

The DID of the delegate requesting access.

capabilities
required
Array of strings
expiresIn
integer

Time in seconds until the token expires.

Responses

Request samples

Content type
application/json

This example shows how to delegate invoice processing capabilities to an AI agent within the 'acme' organization.

{
  • "delegate": "did:human:agent-12345",
  • "capabilities": [
    ],
  • "expiresIn": 3600
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "expiresAt": "2023-10-15T10:00:00Z"
}

Revoke Passport Token by ID

This endpoint gracefully revokes a specific passport token, ensuring it no longer grants access or capabilities. It's crucial for maintaining the integrity and security of the HUMAN ecosystem, as it allows users to effectively manage and revoke permissions when necessary.

Responses

Response samples

Content type
application/json

Successfully revoking a passport token for an organization.

null

Revoke Delegation Token by ID

In the dynamic landscape of the HUMAN platform, delegation tokens empower agents to act on behalf of one another securely. This endpoint allows you to revoke an existing delegation token, ensuring that only authorized actions are performed and maintaining the integrity of the network.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Rotate a Delegation Token Safely

In the HUMAN ecosystem, delegation tokens are the lifeblood of secure interactions. This endpoint allows you to rotate a delegation token, ensuring that access remains current and secure without extending the original delegation period. It's a crucial operation to maintain security and validity in a dynamic environment.

Responses

Response samples

Content type
application/json

An example of a successful token rotation for the 'acme' organization.

{
  • "token": "new-token-string",
  • "delegation_id": "del-123456",
  • "created_at": "2023-10-10T12:00:00Z",
  • "expires_at": "2023-12-31T23:59:59Z"
}

Revoke an existing delegation

This endpoint empowers authorized users to revoke a specific delegation, providing a mechanism for fine-tuned control over permissions. By revoking a delegation, users can ensure that only the right agents maintain access to sensitive resources, reflecting the dynamic nature of trust and responsibility in decentralized networks.

Request Body schema: application/json
required
reason
string

Explanation for revocation

metadata
object

Additional contextual information

Responses

Request samples

Content type
application/json

Revoking a delegation with a specific reason provided.

{
  • "reason": "Access no longer needed",
  • "metadata": {
    }
}

Response samples

Content type
application/json
null

Retrieve deployment's verification status

In an interconnected digital ecosystem, understanding your deployment's verification status is pivotal. This endpoint unravels whether your deployment's passports are network verified or confined to local validation, a crucial distinction in maintaining security integrity.

Responses

Response samples

Content type
application/json

An example scenario where the deployment is verified only locally.

{
  • "network_verification": "local_only",
  • "explanation": "Passports on this deployment are verified locally. Network-wide verification requires distributed ledger integration (v0.3).",
  • "mitigations": [
    ],
  • "risks": {
    },
  • "recommendations": [
    ]
}

Revoke a specific passport grant

In the intricate dance of digital identity, sometimes you need to call back a partner. This endpoint allows a user to revoke a specific grant, immediately updating its status. It ensures that only the rightful owner of the digital identity can perform such a critical action, maintaining trust in our distributed ecosystem.

Request Body schema: application/json
required
reason
string

Reason for revocation, providing context for the action

Responses

Request samples

Content type
application/json

Revoking a grant with an explanation

{
  • "reason": "No longer needed for current project"
}

Response samples

Content type
application/json
{
  • "grant_id": "grant_12345",
  • "grant_type": "delegation",
  • "status": "revoked",
  • "revoked_at": "2023-10-12T08:45:30Z",
  • "revoked_by": "did:example:123456789abcdefghi",
  • "reason": "No longer required"
}

Authorize a device for identity verification

In the HUMAN protocol, safeguarding your cryptographic identity is crucial. This endpoint allows users to initiate device authorization for a DID, setting the stage for secure WebAuthn interactions. By leveraging this, users can ensure their identity is protected and verified through trusted devices.

Responses

Response samples

Content type
application/json

An example where the device authorization options are successfully generated for a valid DID.

{
  • "challenge_id": "c1234567890",
  • "options": {
    }
}

Revoke a Device from a Passport

In the complex dance of digital identity, sometimes a device needs to gracefully exit the stage. This endpoint allows you to revoke a device from a user's Passport, ensuring that access is controlled and secure. Whether it's a lost device or a change in access policy, this operation keeps your digital space safe.

Request Body schema: application/json
required
One of
required
object
revocation_reason
string
request_id
string

Responses

Request samples

Content type
application/json

Revoking a device with a reason and request ID

{
  • "authorization": {
    },
  • "revocation_reason": "Device lost",
  • "request_id": "req-789"
}

Response samples

Content type
application/json
{
  • "device_id": "device-abc",
  • "revoked_at": "2023-10-05T14:48:00.000Z",
  • "status": "revoked",
  • "revocation_event_id": "rev-event-123"
}

Request WebAuthn Options for Disclosure

Unlock the potential of secure identity verification by requesting WebAuthn options for a pending disclosure. This endpoint ensures that only the valid subject of a disclosure request can initiate the WebAuthn process, thus preserving the integrity and security of the HUMAN protocol.

Responses

Response samples

Content type
application/json

An example where a subject successfully retrieves WebAuthn options for a pending disclosure request.

{
  • "challenge_id": "5f8d04b3-8d3d-4c2a-8a9e-1234567890ab",
  • "options": {
    }
}

Grant Passport Disclosure Request

Empower digital identities by granting disclosure requests through secure WebAuthn verification. This endpoint ensures that only authorized parties can disclose sensitive attributes, maintaining the integrity and trust within the HUMAN platform.

Request Body schema: application/json
required
required
object
required
Array of objects

A list of attributes that the subject is granting.

denied_attributes
Array of strings

A list of attributes that the subject is denying.

Responses

Request samples

Content type
application/json

Demonstrates granting disclosure with valid WebAuthn and attributes.

{
  • "webauthn": {
    },
  • "granted_attributes": [
    ],
  • "denied_attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "request_id": "request123",
  • "status": "granted",
  • "granted_at": "2023-10-05T14:48:00.000Z",
  • "disclosure_token": "pdt_exampletoken",
  • "expires_at": "2023-10-06T14:48:00.000Z"
}

Revoke a connector's credential securely

In the intricate dance of data security, credentials sometimes lose their rhythm. This endpoint lets you gracefully revoke a credential, ensuring that your organization maintains its harmony. With the power of Passport delegation, only the maestro—the org admin or credential owner—can call the shots.

Responses

Response samples

Content type
application/json
{
  • "credential_id": "cred-12345",
  • "status": "revoked",
  • "revoked_by": "passport-67890",
  • "revoked_at": "2023-10-08T14:48:00.000Z"
}

Retrieve encrypted secret value by key

Unravel the mystery behind secure data management by retrieving a secret value tied to your organization's cryptographic identity. This endpoint leverages a KMS-backed cascade approach to ensure that your sensitive information is accessible only within the right context, providing robust security and seamless integration.

Responses

Response samples

Content type
application/json

Retrieve the secret value for the 'api-token' key within the context of the 'acme' organization.

{
  • "value": "s3cr3tV4lu3"
}

Create or update a secret securely

Securely store or modify a secret using a cryptographic key, with optional details like expiration and rotatability. This endpoint ensures sensitive information is safeguarded while allowing controlled access and updates, crucial for dynamic environments where secrets must be frequently rotated.

Request Body schema: application/json
required
value
required
string

The secret value to store. This is required.

description
string

Optional description of the secret's purpose

rotatable
boolean

Indicates if the secret can be rotated

expires_at
string <date-time>

The ISO 8601 date when the secret expires

expiresAt
string <date-time>

Legacy field for expiration date

Responses

Request samples

Content type
application/json

An example of an API key that can be rotated and has an expiration date.

{
  • "value": "supersecretapikey123",
  • "description": "API key for external service integration",
  • "rotatable": true,
  • "expires_at": "2024-12-31T23:59:59Z"
}

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Delete Secret by Key

In the evolving landscape of digital orchestration, secrets securely guard access to sensitive operations. This endpoint empowers users to surgically delete a secret, purging it from the current scoped context. By doing so, it ensures that outdated or compromised credentials are swiftly retired, maintaining the integrity and security of the systems they protect.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Rotate a secret to a new value

Secrets are the lifeblood of secure systems, and rotating them periodically ensures their integrity. This endpoint allows you to rotate an existing secret to a new value, fortifying your security posture against potential vulnerabilities. The dual support for both new_value and newValue caters to modern and legacy clients alike, ensuring a smooth transition in your security practices.

Request Body schema: application/json
required
One of
new_value
required
string

The new secret value to replace the existing one.

Responses

Request samples

Content type
application/json
Example

Rotating a secret using the modern new_value field.

{
  • "new_value": "newSecret123!"
}

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve organization's secret keys

Embark on a journey through the vault of secrets tailored for your organization. This endpoint is your key to uncovering cryptographic treasures, filtered by an optional prefix to hone in on specific secrets. Whether you're securing data or managing credentials, this is an essential tool for orchestrating human-AI interactions with precision.

Responses

Response samples

Content type
application/json

Organization retrieves secret key names to audit credentials.

{
  • "keys": [
    ]
}

Create or Update Vault Access Grant

Orchestrate secure access to organizational vaults by creating or updating access grants. This endpoint ensures that only authenticated users can grant themselves access, reinforcing security by tying cryptographic identity to vault permissions.

Request Body schema: application/json
required
vault_entity_did
required
string

Decentralized identifier of the vault entity (organization)

member_did
required
string

Decentralized identifier of the member requesting access

encrypted_mvk
required
string

Base64-encoded encrypted master vault key

iv
required
string

Base64-encoded initialization vector (12 bytes)

Responses

Request samples

Content type
application/json

A member of Acme Corp granting themselves access to the vault

{
  • "vault_entity_did": "did:example:acme-corp",
  • "member_did": "did:example:john-doe",
  • "encrypted_mvk": "U2FsdGVkX1+abc123456=",
  • "iv": "QUJDREVGRw=="
}

Response samples

Content type
application/json
{
  • "ok": true
}

Store Encrypted Document Securely

Embark on a journey of secure document storage with our vault endpoint. This API endpoint enables you to safely store encrypted documents, ensuring that sensitive data is guarded with precision. By using a cryptographic identity, it maintains integrity and traceability, making it indispensable for organizations like 'acme' that require robust data protection.

Request Body schema: application/json
required
ciphertext
required
string

The encrypted document content, encoded in base64.

iv
required
string

The initialization vector for the encryption, encoded in base64 and must decode to 12 bytes.

object

Optional metadata; each value is arbitrary JSON (Record<string, unknown>) stored as JSONB — not limited to strings.

Responses

Request samples

Content type
application/json

An example of storing an encrypted invoice document.

{
  • "ciphertext": "c3VwZXJzZWNyZXRjb250ZW50",
  • "iv": "dGVzdGluaXQxMjM=",
  • "metadata": {
    }
}

Response samples

Content type
application/json
null

Securely update connector webhook secret

In the ever-evolving world of digital interactions, ensuring secure communication is paramount. This endpoint allows organizations to update the signing secret for their connectors, reinforcing the security of webhook communications. It exists to ensure that data integrity and authenticity are maintained through cryptographic measures, allowing organizations to confidently interact with HUMAN's powerful orchestration capabilities.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve connector's webhook secret metadata

Unlock the orchestration potential of AI-human collaboration by fetching essential webhook secret metadata for a connector. This endpoint ensures secure and reliable communication between your services, safeguarding data integrity and authenticity.

Responses

Response samples

Content type
application/json
null

Deactivate a Connector's Webhook Secret

In a world where data flows seamlessly, connectors play a crucial role in linking systems. This endpoint allows organizations to deactivate the webhook secret for a specific connector, enhancing security by disabling outdated or compromised integrations. By doing so, it ensures that the data shared through these connectors remains secure and controlled.

Responses

Response samples

Content type
application/json

Successfully deactivating the webhook secret for connector ID 1234

{
  • "connector_id": "1234",
  • "active": false,
  • "deactivated_at": "2023-12-01T12:34:56Z"
}

Export marketplace bundle for offline review

In the world of secure data management, reviewing asset bundles offline is crucial for maintaining air-gap security. This endpoint facilitates the export of a signed bundle, complete with an HMAC manifest and member digests, allowing you to safely review your assets without an active network connection.

Request Body schema: application/json
required
bundle_asset_id
required
string

The unique identifier of the bundle to export

Responses

Request samples

Content type
application/json

Exporting the asset bundle with ID 'bundle-12345' for review by Acme Corp's security team.

{
  • "bundle_asset_id": "bundle-12345"
}

Response samples

Content type
application/json
{
  • "hmac_manifest": "hmac-abc123",
  • "member_digests": [
    ]
}

Create a new API signing key

This endpoint allows you to create a named Human API signing key linked to a specific passport. API signing keys are essential for securing session-based operations, ensuring that all interactions are traceable to a verified identity. This feature provides an additional layer of security and traceability within the HUMAN ecosystem.

Request Body schema: application/json
required
label
required
string

A human-readable label for the API signing key. Maximum 128 characters.

Responses

Request samples

Content type
application/json

Creating a signing key for the 'acme-invoice-processing' application.

{
  • "label": "acme-invoice-processing-key"
}

Response samples

Content type
application/json

Response after successfully creating a signing key for 'acme-invoice-processing'.

{
  • "key_id": "hask_123456789",
  • "public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAn...",
  • "fingerprint": "3F:9F:6B:2D:EE:4A:08:3B:4B:54:C6:03:9C:2D:7C:1D",
  • "label": "acme-invoice-processing-key",
  • "created_at": "2023-10-21T14:32:28Z"
}

Retrieve active API signing keys

Discover the active cryptographic keys that secure communications with HUMAN API. This endpoint is vital for ensuring the integrity and authenticity of interactions by listing the valid keys tied to a Passport, empowering trusted integration.

Responses

Response samples

Content type
application/json

Shows a Passport with multiple active API signing keys and pagination.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Retrieve specific API signing key metadata

Explore the cryptographic essence of your identity with the Passport's API signing key metadata. This endpoint unveils the details of a specific active key, enabling secure and traceable interactions within the HUMAN network. Discover when it was created, its fingerprint, and more, as you navigate the digital realm with confidence.

Responses

Response samples

Content type
application/json
{
  • "key_id": "key_12345",
  • "label": "Invoice Processing Key",
  • "fingerprint": "abc123base64encodedfingerprint==",
  • "created_at": "2023-10-01T14:30:00Z",
  • "last_used_at": "2023-10-15T09:00:00Z"
}

Revoke a Human API Signing Key

This endpoint allows you to revoke an API signing key associated with a Human Passport. By invalidating the specified key, you ensure that it can no longer be used to authenticate requests, enhancing security and control over your API access. This is particularly useful when a key is compromised or no longer needed.

Responses

Response samples

Content type
application/problem+json

Occurs when the keyId format does not match the expected pattern.

{}

Generate WebAuthn Recovery Options

In the labyrinth of digital identity, recovery is paramount. This endpoint crafts WebAuthn recovery options for a Human passport, ensuring you never lose access to what's rightfully yours. Designed for only the most human of identities, it locks out the non-human pretenders.

Responses

Response samples

Content type
application/json

A Human passport successfully retrieves WebAuthn recovery options.

{
  • "challenge_id": "abc123xyz",
  • "options": {
    }
}

Rotate WebAuthn Keys for Passport

Securely rotate WebAuthn keys for a human passport, ensuring cryptographic integrity. This endpoint facilitates the transition to new keys by generating necessary WebAuthn options, enhancing the security and trust in identity management.

Responses

Response samples

Content type
application/json

Example of a successful response with WebAuthn registration options.

{
  • "registration_id": "reg_123456789",
  • "options": {
    }
}

Retrieve active passport cryptographic keys

Unlock the potential of secure identity verification by retrieving the active cryptographic keys associated with a specific passport. This endpoint ensures the integrity and authenticity of communications on the HUMAN platform, empowering both humans and AI to interact with confidence.

Responses

Response samples

Content type
application/json

An example response showing keys for Acme Corporation's cryptographic passport.

{
  • "keys": [
    ]
}

Rotate Passport Cryptographic Keys

In the HUMAN ecosystem, maintaining the security of your cryptographic identity is paramount. This endpoint allows passport holders to rotate their keys, ensuring that their digital identity remains secure and up-to-date. By rotating keys, users can refresh their cryptographic credentials, which is essential for maintaining trust and security in their interactions on the platform.

Request Body schema: application/json
required
One of
webauthn_auth
required
object
webauthn_attest
required
object
purposes
Array of strings
Items Enum: "auth" "attest"

Purposes for which the keys are rotated. Must include both 'auth' and 'attest'.

object

WebAuthn credentials for Human passport key rotation.

Responses

Request samples

Content type
application/json

Rotating keys for a Human passport with valid WebAuthn credentials.

{
  • "purposes": [
    ],
  • "webauthn": {
    }
}

Response samples

Content type
application/json
{
  • "passport_id": "did:human:123456789abcdef",
  • "status": "rotated",
  • "auth_key_id": "key_abcdef123456",
  • "attest_key_id": "key_123456abcdef",
  • "retired_at": "2023-10-15T08:55:30Z"
}

Revoke a Passport Key

Securely revoke a cryptographic key associated with a Passport, ensuring it can no longer be used for authentication. This endpoint is vital for maintaining security and control over access, especially in dynamic environments where keys must be invalidated promptly.

Responses

Response samples

Content type
application/json
{
  • "passport_id": "passport_12345",
  • "key_id": "key_67890",
  • "status": "revoked",
  • "revoked_at": "2023-11-05T14:48:00.000Z"
}

Enroll Guardian Recovery for Human Passport

Secure your digital identity with the power of community. This endpoint allows a human passport owner to establish a guardian-based recovery policy. By enlisting trusted guardians, you ensure a safety net for identity recovery, harnessing the strength of social verification.

Request Body schema: application/json
required
required
Array of objects [ 3 .. 5 ] items

An array of 3 to 5 guardian objects.

threshold
integer >= 2

Number of guardians required to approve a recovery.

Responses

Request samples

Content type
application/json

Enrolls three guardians with a threshold of two for recovery.

{
  • "guardians": [
    ],
  • "threshold": 2
}

Response samples

Content type
application/json
{
  • "policy_id": "policy_12345",
  • "type": "guardian",
  • "threshold": 2,
  • "guardians": [
    ],
  • "sss_enabled": true,
  • "sss_guardian_count": 3
}

Retrieve Passport Recovery Requests

In the world of digital identity, recovery is paramount. This endpoint lets you peek into the requests for recovering a passport, ensuring your digital identity's safety. Dive into a list of recovery attempts to audit and maintain control over your cryptographic identity.

Responses

Response samples

Content type
application/json

An example response showcasing a typical list of recovery requests.

{
  • "data": [
    ],
  • "pagination": {
    }
}

Initiate Passport Recovery Process

Create a recovery request to regain access to a cryptographic passport, ensuring identity continuity in secure environments. This endpoint is the first step in safeguarding and restoring access when a passport is compromised or lost, leveraging HUMAN's robust identity framework.

Request Body schema: application/json
required
expiresAt
string <date-time>

The expiration date and time of the recovery request. If not provided, defaults to a predefined TTL.

reason
required
string

The reason for initiating this recovery request, providing context for auditing.

Responses

Request samples

Content type
application/json

An example where the recovery request is created for a lost passport.

{
  • "expiresAt": "2023-12-31T23:59:59Z",
  • "reason": "Lost access to my cryptographic key"
}

Response samples

Content type
application/json
{
  • "request_id": "req_1234567890",
  • "status": "pending",
  • "policy_id": "pol_0987654321",
  • "expires_at": "2023-12-31T23:59:59Z"
}

Generate Single-Use Recovery Keys

In the labyrinth of identity, sometimes you need a lifeline. This endpoint crafts a new set of 10 single-use recovery keys for your passport, ensuring you can always find your way back. These keys are your safety net, providing a secure way to regain access when all else fails. The keys are delivered just once, like a message in a bottle, so keep them safe.

Responses

Response samples

Content type
application/json

An example of a successful recovery key generation for a user's passport.

{
  • "recovery_keys": [
    ],
  • "count": 10,
  • "warning": "These keys are displayed only once. Store them securely."
}

Regenerate Passport Recovery Keys

In the ever-evolving landscape of digital identities, keeping your recovery keys secure is paramount. This endpoint gives you the power to regenerate your recovery keys, seamlessly revoking the old set and ensuring your digital identity remains protected. It's about safeguarding your credentials with a simple request.

Responses

Response samples

Content type
application/json

A user from the 'acme' organization successfully regenerates their recovery keys.

{
  • "recovery_keys": [
    ],
  • "count": 3,
  • "warning": null
}

Retrieve Remaining Recovery Keys

In the realm of digital identity, safeguarding access is paramount. This endpoint empowers users to check the status of their recovery keys without revealing sensitive details, ensuring they maintain a robust security posture. By understanding the balance of used, remaining, and total keys, users can navigate their recovery strategy with confidence.

Responses

Response samples

Content type
application/json

A response indicating the user has used some of their recovery keys.

{
  • "total": 5,
  • "remaining": 3,
  • "used": 2,
  • "generated": "2023-10-05T14:48:00.000Z"
}

Execute Passport Recovery Process

Unlock access to your digital identity with a secure, two-step recovery process. Using a single-use recovery key, this endpoint enables users to regain control of their Passport when their primary passkey is lost. Experience peace of mind with aggressive security measures protecting against unauthorized access.

Request Body schema: application/json
required
One of
step
required
string
Value: "initiate"
passport_hint
required
string

Hint for the passport identity, typically an email or DID

recovery_key
required
string

Single-use recovery key provided during initial setup

Responses

Request samples

Content type
application/json
Example

Example of the initial recovery request with recovery key and passport hint.

{
  • "step": "initiate",
  • "passport_hint": "user@example.com",
  • "recovery_key": "recovery-key-1234"
}

Response samples

Content type
application/json
Example
{
  • "registration_id": "reg-9876",
  • "options": {
    },
  • "recovery_token": "token-5678"
}

Verify a complete authority chain

In the intricate dance between human and AI, ensuring trustworthiness is paramount. This endpoint verifies the cryptographic integrity of an authority chain, documenting each step in the provenance ledger. Whether you're verifying an organization or an individual agent, this process guarantees that only legitimate entities hold power.

Request Body schema: application/json
required
One of
agent_did
required
string

Decentralized Identifier for the agent.

org_did
string

Decentralized Identifier for the organization.

mode
string
Enum: "full" "cached" "delegation-only"

Verification mode: full, cached, or delegation-only.

Responses

Request samples

Content type
application/json
Example

Verify the authority chain for an individual agent.

{
  • "agent_did": "did:agent:1234abcd",
  • "mode": "full"
}

Response samples

Content type
application/json

An agent's authority chain verified with no issues.

{
  • "agent_did": "did:agent:1234abcd",
  • "verification_mode": "full",
  • "valid": true,
  • "chain": {
    },
  • "errors": [ ],
  • "verified_at": "2023-10-04T14:48:00.000Z"
}

Complete Guardian Recovery Process

Unlock your digital identity by completing the guardian recovery process. This endpoint is the final step in securing your Passport's credentials after meeting the quorum of guardians and waiting for the lock period to expire. It's not just a transaction—it's the rebirth of trust and security in your digital realm.

Request Body schema: application/json
required
registration_id
required
string

Unique identifier for the new device registration.

required
object

Cryptographic credential for the new device.

Responses

Request samples

Content type
application/json

Completing recovery for a user moving credentials to a new device.

{
  • "registration_id": "reg_123456789",
  • "credential": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Guardian recovery completed successfully."
}

Store Encrypted Recovery Backup

Preserve your digital identity's resilience by securely storing an encrypted recovery backup for your HUMAN Passport. This ensures you can recover your cryptographic identity even if local credentials are lost, without compromising your passphrase.

Request Body schema: application/json
required
encrypted_blob
required
string

AES-256-GCM encrypted data blob

storage_hint
string
Enum: "icloud" "gdrive" "onedrive" "other"

Optional storage provider hint

Responses

Request samples

Content type
application/json

A typical encrypted backup to Google Drive

{
  • "encrypted_blob": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ...",
  • "storage_hint": "gdrive"
}

Response samples

Content type
application/json

Response indicating successful storage of encrypted backup.

{
  • "stored": true,
  • "updated_at": "2023-10-12T07:20:50.52Z"
}

Restore encrypted cloud backup

This endpoint allows users to securely restore their encrypted cloud backup for a passport, ensuring data sovereignty and privacy. By leveraging WebAuthn authentication, it verifies device ownership, facilitating client-side decryption and maintaining the integrity of sensitive information.

Responses

Response samples

Content type
application/json

A user successfully retrieves their encrypted cloud backup for decryption.

{
  • "encrypted_blob": "U2FsdGVkX1+I5Jql7Q==",
  • "storage_hint": "us-east-1",
  • "backed_up_at": "2023-10-15T14:48:00Z"
}

Retrieve Passport Device Revocation Events

Explore the journey of your cryptographic identity by accessing a history of device revocation events linked to your HUMAN Passport. This endpoint enables users to verify and understand the security actions taken on their devices, ensuring transparency and trust in the orchestration between humans and AI.

Responses

Response samples

Content type
application/json

An example showing a set of device revocation events for a specific passport.

{
  • "data": [
    ],
  • "hub_public_key": "public_key_base64url"
}

Complete Recovery with Proof

This endpoint finalizes the recovery of a cryptographic identity using client-side reconstructed HMAC proof. It empowers users to securely reclaim their digital identity in a decentralized manner, ensuring that only legitimate recovery requests are completed.

Request Body schema: application/json
required
proof_of_reconstruction
required
string

A cryptographic proof to verify the reconstruction process.

new_device_public_key
required
string

The public key of the new device to associate with the identity.

registration_id
required
string

Unique identifier for the registration process.

credential
required
object

Additional credential details required for verification.

Responses

Request samples

Content type
application/json

An example of a successful recovery request with all necessary fields.

{
  • "proof_of_reconstruction": "hmac-encoded-proof",
  • "new_device_public_key": "new-device-public-key",
  • "registration_id": "reg123456",
  • "credential": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Recovery completed successfully.",
  • "new_device_id": "device123"
}

Claim Pending Evidence

Securely claim pending evidence using your cryptographic identity (Passport). This endpoint ensures evidence can only be claimed by the rightful owner, with anti-fraud measures to prevent misuse.

Responses

Response samples

Content type
application/json
{
  • "evidence_record": {
    },
  • "claimed": true
}

Safely remove capability definition

This endpoint allows you to delete a capability definition when it is safe to do so. It ensures that no active nodes or grants are referencing the definition, maintaining the integrity of the system. Explore the dynamics of capability management as you streamline your organization's skills graph.

Responses

Response samples

Content type
application/json

A capability definition removed from the system successfully.

{
  • "capability_id": "def456",
  • "deleted": true,
  • "deleted_at": "2023-10-14T08:42:00Z"
}

Generate a Capability Proof

Unlock the potential of your digital identity by generating a cryptographic proof of capabilities tied to your Passport. This endpoint ensures active capability grants, empowering secure and verifiable interactions across the HUMAN platform.

Request Body schema: application/json
required
did
required
string

Passport decentralized identifier (DID)

capabilities
required
Array of strings

List of capability identifiers to prove

proof_type
string
Default: "attestation"

Type of proof, defaults to 'attestation'

valid_for
integer

Duration in seconds for which the proof is valid

Responses

Request samples

Content type
application/json

Requesting a proof for specific capabilities linked to a Passport DID.

{
  • "did": "did:human:acme:12345",
  • "capabilities": [
    ],
  • "proof_type": "attestation",
  • "valid_for": 3600
}

Response samples

Content type
application/json

Proof created for a user's capabilities with a verification link.

{
  • "proof_id": "proof_67890",
  • "proof_data": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "capabilities_proven": [
    ],
  • "created_at": "2023-10-26T15:30:00Z",
  • "expires_at": "2023-10-26T16:30:00Z",
  • "verification_url": "https://verify.human.xyz/proofs/proof_67890"
}

Register or update MCP session details

This endpoint allows internal components of the HUMAN platform to register or update sessions for multi-capability processing (MCP). By managing session lifecycles, it ensures seamless orchestration of tasks across human and AI agents under secure conditions.

Request Body schema: application/json
required
session_id
required
string

Unique identifier for the session

passport_id
required
string

Cryptographic identity of the agent

org_did
required
string

Decentralized identifier for the organization

scopes
Array of strings

List of permissions granted to the session

client_name
string

Name of the client creating the session

plan_tier
string or null

Service plan tier (if applicable)

expires_at
required
string <date-time>

Expiration timestamp for the session

Responses

Request samples

Content type
application/json

Registers a session for the 'acme' organization with specific scopes and a premium plan tier.

{
  • "session_id": "session_12345",
  • "passport_id": "passport_abcde",
  • "org_did": "did:humanos:acme",
  • "scopes": [
    ],
  • "client_name": "Acme Client",
  • "plan_tier": "premium",
  • "expires_at": "2023-12-31T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Revoke an MCP session by ID

In the ever-evolving landscape of AI-driven tasks, sessions are the lifeline of task processing. This endpoint allows authorized users to revoke a session, ensuring that outdated or unauthorized sessions don't linger, maintaining the integrity and security of our Human-AI orchestration.

Responses

Response samples

Content type
application/json
null

Identity Management

List Issuer Delegation Tokens

Retrieve a curated list of delegation tokens issued by or to your identity, enabling seamless management of access permissions. This endpoint empowers you to monitor and manage the lifecycle of delegation tokens, ensuring your digital interactions are secure and traceable.

Responses

Response samples

Content type
application/json

An example of retrieving a list of delegation tokens for issuer 'acme'.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": false
}

Authorize a device for identity verification

In the HUMAN protocol, safeguarding your cryptographic identity is crucial. This endpoint allows users to initiate device authorization for a DID, setting the stage for secure WebAuthn interactions. By leveraging this, users can ensure their identity is protected and verified through trusted devices.

Responses

Response samples

Content type
application/json

An example where the device authorization options are successfully generated for a valid DID.

{
  • "challenge_id": "c1234567890",
  • "options": {
    }
}

Create a New Cryptographic Identity

Embark on a journey to establish a cryptographic identity through our Passport system, enabling secure and verifiable interactions within the HUMAN platform. This endpoint orchestrates the identity creation process with idempotent guarantees ensuring consistent outcomes.

Responses

Response samples

Content type
application/json

A successful response showing the newly created identity and its enrollment data.

{
  • "id": "identity-12345",
  • "enrollmentData": {
    }
}

Initiate guardian-mediated recovery process

Embark on a journey to reclaim control of your cryptographic identity through the trusted hands of your appointed guardians. This endpoint kicks off a guardian-mediated recovery process, locking the Passport for a 48-hour window, ensuring security and deliberate action.

Request Body schema: application/json
required
reason
string

The reason for initiating recovery. Helps guardians understand the context.

completion_mode
required
string
Enum: "server_assembly" "client_proof"

Defines the completion process, either controlled by the server or client.

Responses

Request samples

Content type
application/json

Initiate recovery because the user lost access to their Passport.

{
  • "reason": "Lost access to Passport",
  • "completion_mode": "server_assembly"
}

Response samples

Content type
application/json

The request was processed, and the recovery sequence has begun.

{
  • "message": "Guardian recovery process initiated successfully.",
  • "lock_period": 48
}

Retrieve Passport Device Revocation Events

Explore the journey of your cryptographic identity by accessing a history of device revocation events linked to your HUMAN Passport. This endpoint enables users to verify and understand the security actions taken on their devices, ensuring transparency and trust in the orchestration between humans and AI.

Responses

Response samples

Content type
application/json

An example showing a set of device revocation events for a specific passport.

{
  • "data": [
    ],
  • "hub_public_key": "public_key_base64url"
}

Complete Recovery with Proof

This endpoint finalizes the recovery of a cryptographic identity using client-side reconstructed HMAC proof. It empowers users to securely reclaim their digital identity in a decentralized manner, ensuring that only legitimate recovery requests are completed.

Request Body schema: application/json
required
proof_of_reconstruction
required
string

A cryptographic proof to verify the reconstruction process.

new_device_public_key
required
string

The public key of the new device to associate with the identity.

registration_id
required
string

Unique identifier for the registration process.

credential
required
object

Additional credential details required for verification.

Responses

Request samples

Content type
application/json

An example of a successful recovery request with all necessary fields.

{
  • "proof_of_reconstruction": "hmac-encoded-proof",
  • "new_device_public_key": "new-device-public-key",
  • "registration_id": "reg123456",
  • "credential": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Recovery completed successfully.",
  • "new_device_id": "device123"
}

Remove a user's consent policy

In the HUMAN protocol, consent is crucial. This endpoint allows the owner of a cryptographic identity, or Passport, to remove a consent policy they've previously granted. It's a step towards empowering users by giving them control over their personal data and how it's shared.

Responses

Response samples

Content type
application/json

The consent policy with ID 'policy-1234-5678' was successfully removed.

{
  • "ok": true,
  • "id": "policy-1234-5678"
}

Delegation

List Issuer Delegation Tokens

Retrieve a curated list of delegation tokens issued by or to your identity, enabling seamless management of access permissions. This endpoint empowers you to monitor and manage the lifecycle of delegation tokens, ensuring your digital interactions are secure and traceable.

Responses

Response samples

Content type
application/json

An example of retrieving a list of delegation tokens for issuer 'acme'.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": false
}

Retrieve Delegation Token Details

Uncover the secrets of delegation by fetching detailed information about a specific delegation token. This endpoint empowers you to navigate the intricacies of digital identity and access control, ensuring that every interaction is securely tracked and validated through the HUMAN platform.

Responses

Response samples

Content type
application/json
{
  • "delegation_id": "del_123456",
  • "token_id": "tok_78910",
  • "scope": [
    ],
  • "expires_at": "2023-12-31T23:59:59Z",
  • "created_at": "2023-01-01T00:00:00Z",
  • "last_used_at": "2023-09-15T12:34:56Z",
  • "revoked_at": null
}

Revoke Delegation Token by ID

In the dynamic landscape of the HUMAN platform, delegation tokens empower agents to act on behalf of one another securely. This endpoint allows you to revoke an existing delegation token, ensuring that only authorized actions are performed and maintaining the integrity of the network.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve tokens by delegation ID

Discover the lifeline of your delegation tokens with a simple query. This endpoint empowers you to list tokens tied to a specific delegation, ensuring precise control and oversight of token usage within the HUMAN ecosystem.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Rotate a Delegation Token Safely

In the HUMAN ecosystem, delegation tokens are the lifeblood of secure interactions. This endpoint allows you to rotate a delegation token, ensuring that access remains current and secure without extending the original delegation period. It's a crucial operation to maintain security and validity in a dynamic environment.

Responses

Response samples

Content type
application/json

An example of a successful token rotation for the 'acme' organization.

{
  • "token": "new-token-string",
  • "delegation_id": "del-123456",
  • "created_at": "2023-10-10T12:00:00Z",
  • "expires_at": "2023-12-31T23:59:59Z"
}

Revoke an existing delegation

This endpoint empowers authorized users to revoke a specific delegation, providing a mechanism for fine-tuned control over permissions. By revoking a delegation, users can ensure that only the right agents maintain access to sensitive resources, reflecting the dynamic nature of trust and responsibility in decentralized networks.

Request Body schema: application/json
required
reason
string

Explanation for revocation

metadata
object

Additional contextual information

Responses

Request samples

Content type
application/json

Revoking a delegation with a specific reason provided.

{
  • "reason": "Access no longer needed",
  • "metadata": {
    }
}

Response samples

Content type
application/json
null

Exchange Session for Scoped Delegation Token

Transform your session token into a powerful delegation token, granting you precise capabilities across the HUMAN API. Whether you're managing tasks or accessing resources, this endpoint empowers you to define the scope of your activities securely.

Request Body schema: application/json
required
capabilities
Array of strings

List of requested capabilities. Defaults to a standard set if omitted.

orgDid
string

Optional organizational DID for role-based scope.

required_verification_tier
number

Minimum verification tier required for this delegation.

required_identity_tier
number

Minimum identity tier required for this delegation.

duration_seconds
number

Duration for which the delegation token is valid, in seconds.

environment
string

Specific environment constraints for the delegation.

risk_level
string
Enum: "low" "standard" "high"

Risk level associated with the delegation.

Responses

Request samples

Content type
application/json
Example

Request with default capabilities and 24-hour duration.

{
  • "capabilities": [ ],
  • "duration_seconds": 86400
}

Response samples

Content type
application/json
{
  • "delegation_id": "del_123456789",
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "passport_id": "did:example:user123",
  • "did": "did:example:user123",
  • "capabilities": [
    ],
  • "verification_tier": 2,
  • "identity_tier": 3,
  • "created_at": "2023-10-01T12:00:00Z",
  • "expires_at": "2023-10-02T12:00:00Z",
  • "has_companion_cp_read": false
}

Narrow scopes on a delegation grant

In the intricate dance of permissions and trust, sometimes it becomes necessary to tighten the reins. This endpoint allows an organization to refine the permissions they've granted, ensuring the recipient can only access what's truly essential. It's about maintaining control in a dynamic environment.

Request Body schema: application/json
required
scopes
required
Array of strings

A strict subset of the current scopes to narrow the delegation.

constraints
required
object

Additional conditions applied to the delegation grant.

Responses

Request samples

Content type
application/json

An example where the grant is narrowed to only include 'read:invoices' scope.

{
  • "scopes": [
    ],
  • "constraints": {
    }
}

Response samples

Content type
application/json
null

Pause an active delegation grant

In the intricate dance of human and AI collaboration, there may come a time when a delegation grant needs a pause — a momentary rest to reassess or reallocate resources. This endpoint allows you to hit that pause button, ensuring the grant remains dormant yet poised for future reactivation.

Responses

Response samples

Content type
application/json

Pausing a delegation grant for the 'acme' organization.

{
  • "delegation_id": "grant_12345",
  • "status": "paused",
  • "grantor_did": "did:human:acme"
}

Unpause a paused delegation grant

In the symphony of human and AI collaboration, sometimes we need to hit pause. But when you're ready to resume the dance, this endpoint lets you seamlessly transition a paused delegation grant back to its active state. It's your cue to continue orchestrating magic.

Responses

Response samples

Content type
application/json

Successfully unpausing a delegation grant for user interaction to continue.

{
  • "delegation_id": "grant_12345",
  • "status": "active"
}

Delegate Capabilities with JWT

This endpoint allows the creation of a delegation JWT from an issuer's passport, enabling secure sharing of capabilities. By delegating specific roles and permissions, organizations and agents can orchestrate tasks efficiently while maintaining control over access and expiry.

Request Body schema: application/json
required
toPassportId
required
string

The DID of the passport receiving the delegation.

scope
required
Array of strings

Array of capability IDs to be delegated.

expiresAt
string <date-time>

Optional expiration date for the delegation.

resources
Array of strings

Optional list of resource identifiers.

object

Optional constraints for the delegation.

signing_key_id
string

Optional ID for Human API signing key, required for human issuers.

Responses

Request samples

Content type
application/json

Delegating invoice processing capabilities to an agent in the 'acme' organization.

{
  • "toPassportId": "did:human:1234abc",
  • "scope": [
    ],
  • "expiresAt": "2024-12-31T23:59:59Z",
  • "resources": [
    ],
  • "conditions": {
    }
}

Response samples

Content type
application/json
{
  • "delegation_id": "dtok_5678def",
  • "from_passport_id": "did:human:5678def",
  • "to_passport_id": "did:human:1234abc",
  • "scope": [
    ],
  • "resources": [
    ],
  • "status": "active",
  • "conditions": {
    },
  • "expires_at": "2024-12-31T23:59:59Z",
  • "created_at": "2023-10-01T12:00:00Z",
  • "delegation_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Authentication

Initiate device code authorization flow

Embark on a secure journey to connect devices through cryptographic identity with the HUMAN platform. This endpoint enables applications to request a device code for device authorization, ensuring only verified devices can access protected resources.

Request Body schema: application/json
required
client_id
required
string

The unique identifier for the client application.

scope
required
string

Space-delimited OAuth scopes requested by the client.

Responses

Request samples

Content type
application/json

A typical request from the 'acme' organization to authorize a new device for processing invoices.

{
  • "client_id": "acme-device-client",
  • "scope": "invoice:read invoice:write"
}

Response samples

Content type
application/json
{}

Exchange device code for access token

In the heart of HUMAN's secure ecosystem, this endpoint transforms a granted device code into a powerful access token. It ensures devices can autonomously authenticate while maintaining strict access controls, empowering seamless Human-AI interactions.

Request Body schema: application/json
required
grant_type
required
string
Value: "urn:ietf:params:oauth:grant-type:device_code"

The OAuth grant type for device code exchange

device_code
required
string

The device code obtained from the device authorization request

client_id
required
string

The client identifier for the device

Responses

Request samples

Content type
application/json

A typical request to exchange a device code for an access token

{
  • "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  • "device_code": "123456",
  • "client_id": "acme_device_client"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "refresh_token": "dtr_abc123xyz987",
  • "scope": "read write"
}

Create Personal Access Token

Generate a secure Personal Access Token (PAT) to authenticate and authorize specific capabilities on the HUMAN platform. This enables users to define scopes for their tokens, ensuring precise skill delegation and operational security.

Request Body schema: application/json
required
name
required
string

Descriptive name for the token

scopes
required
Array of strings

Array of capability URIs defining the token's permissions

expires_in
string

Duration before the token expires, e.g., '1h', '30m'

risk_level
string
Enum: "low" "standard" "high"

Risk level associated with the token

environment
string
Enum: "dev" "staging" "production"

Environment where the token is valid

Responses

Request samples

Content type
application/json

Creating a token with read-only access for development environment

{
  • "name": "Dev Read-Only Token",
  • "scopes": [
    ],
  • "expires_in": "1h",
  • "risk_level": "low",
  • "environment": "dev"
}

Response samples

Content type
application/json
{
  • "token_id": "tok_1234567890",
  • "token": "HPAT_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "name": "Dev Read-Only Token",
  • "scopes": [
    ],
  • "created_at": "2023-10-31T12:34:56Z",
  • "expires_at": "2023-10-31T13:34:56Z"
}

Authorize client with OAuth protocol

Initiate an OAuth authorization flow for a client application using the HUMAN Passport. This endpoint ensures that only verified applications can request access, protecting users and maintaining system integrity.

Responses

Response samples

Exchange authorization code for access token

Unlock the potential of your applications by exchanging an authorization code for an access token. This endpoint safeguards the integrity of your interactions by ensuring strict adherence to OAuth standards, empowering developers to harness secure and seamless user authentication.

Request Body schema: application/json
required
grant_type
required
string
Value: "authorization_code"

The type of grant being used. Must be 'authorization_code'.

code
required
string

The authorization code received from the authorization server.

redirect_uri
required
string <uri>

The redirect URI used in the authorization request.

client_id
required
string

The client identifier issued to the client during the registration process.

client_secret
string

The client secret issued to the client during the registration process.

code_verifier
required
string >= 43 characters

The code verifier for PKCE validation.

Responses

Request samples

Content type
application/json

Demonstrates a typical request to exchange an authorization code for an access token.

{
  • "grant_type": "authorization_code",
  • "code": "abc123xyz",
  • "redirect_uri": "https://example.com/callback",
  • "client_id": "acme-client-id",
  • "client_secret": "acme-client-secret",
  • "code_verifier": "verifier1234567890abcdefghijklmnopqrstuvwxyzABCDEF"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "scope": "read:invoices write:invoices"
}

Initiate OAuth Flow for Connector

This endpoint empowers organizations to seamlessly start an OAuth authentication process for a specified connector, ensuring secure connectivity and identity delegation. It exists to facilitate secure integrations while maintaining human oversight in AI orchestration.

Request Body schema: application/json
required
return_url
string

URL to redirect after authorization

Responses

Request samples

Content type
application/json

Starts the OAuth process and specifies where to redirect upon completion.

{}

Response samples

Content type
application/json

The OAuth process is started, providing URLs for user redirection.

{}

Initiate WebAuthn registration for human passports

This endpoint orchestrates the creation of WebAuthn options, a critical step in human passport registration. It ensures a secure and verified identity by leveraging advanced cryptographic techniques, making sure only human entities can proceed. This process stands as a gatekeeper, safeguarding the integrity of the HUMAN platform's ecosystem.

Request Body schema: application/json
required
One of
display_name
required
string

User's display name for the WebAuthn registration process

person_type
required
string
Value: "Human"

Type of person, must be 'Human' for this registration

Responses

Request samples

Content type
application/json

A typical registration request for a human passport

{
  • "display_name": "Alice Doe",
  • "person_type": "Human"
}

Response samples

Content type
application/json
{
  • "registration_id": "reg_12345678",
  • "options": {
    }
}

Initiate WebAuthn login challenge

Embark on a secure journey of authentication with WebAuthn. This endpoint crafts a unique challenge for users aiming to log in via public-key credentials, ensuring a robust identity verification process. It's the first step in fortifying your digital space with cryptographic assurance.

Request Body schema: application/json
required
One of
passport_hint
required
string

A hint for the passport, such as an email.

Responses

Request samples

Content type
application/json
Example

An example showcasing the use of snake_case passport_hint.

{
  • "passport_hint": "user@example.com"
}

Response samples

Content type
application/json

A typical response showing the generated challenge and options for a user attempting login.

{
  • "challenge_id": "challenge_1234567890abcdef",
  • "options": {
    }
}

Authenticate using WebAuthn and issue JWT

Seamlessly authenticate users by verifying a WebAuthn assertion and issuing a short-lived JWT session token. This endpoint safeguards digital identities using cryptographic validation, ensuring only verified users can access sensitive delegation exchanges.

Request Body schema: application/json
required
challenge_id
required
string

Unique identifier for the WebAuthn challenge

credential
required
object

WebAuthn credential assertion object

Responses

Request samples

Content type
application/json

A typical request using a WebAuthn credential to authenticate.

{
  • "challenge_id": "ch_1234567890abcdef",
  • "credential": {
    }
}

Response samples

Content type
application/json

The response returned after a successful authentication.

{
  • "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "passport_id": "did:human:123456789abcdef",
  • "did": "did:human:123456789abcdef",
  • "display_name": "Alice Doe",
  • "verification_tier": "verified",
  • "identity_tier": "silver",
  • "expires_at": "2023-10-01T12:00:00Z"
}

DeviceFlow

Initiate device code authorization flow

Embark on a secure journey to connect devices through cryptographic identity with the HUMAN platform. This endpoint enables applications to request a device code for device authorization, ensuring only verified devices can access protected resources.

Request Body schema: application/json
required
client_id
required
string

The unique identifier for the client application.

scope
required
string

Space-delimited OAuth scopes requested by the client.

Responses

Request samples

Content type
application/json

A typical request from the 'acme' organization to authorize a new device for processing invoices.

{
  • "client_id": "acme-device-client",
  • "scope": "invoice:read invoice:write"
}

Response samples

Content type
application/json
{}

Device Flow

Exchange device code for access token

In the heart of HUMAN's secure ecosystem, this endpoint transforms a granted device code into a powerful access token. It ensures devices can autonomously authenticate while maintaining strict access controls, empowering seamless Human-AI interactions.

Request Body schema: application/json
required
grant_type
required
string
Value: "urn:ietf:params:oauth:grant-type:device_code"

The OAuth grant type for device code exchange

device_code
required
string

The device code obtained from the device authorization request

client_id
required
string

The client identifier for the device

Responses

Request samples

Content type
application/json

A typical request to exchange a device code for an access token

{
  • "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  • "device_code": "123456",
  • "client_id": "acme_device_client"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "refresh_token": "dtr_abc123xyz987",
  • "scope": "read write"
}

Device Management

Confirm device authorization with user code

In the world of distributed identity, confirming a device's authorization is crucial for seamless access. This endpoint allows a device to authenticate using a unique user code, ensuring that only trusted devices can operate within the HUMAN ecosystem. It's a vital step in maintaining the security and integrity of digital identities.

Request Body schema: application/json
required
user_code
required
string

A unique code to verify the device, formatted as XXXX-XXXX.

Responses

Request samples

Content type
application/json

A typical request with a correctly formatted user code.

{
  • "user_code": "WDJB-MJHT"
}

Response samples

Content type
application/json
{
  • "user_code": "WDJB-MJHT",
  • "status": "approved",
  • "subject_did": "did:example:123456789abcdefghi"
}

Register device options for a passport

In the HUMAN ecosystem, binding devices to digital identities is crucial for secure interactions. This endpoint generates registration options, allowing a device to be securely linked to a human passport. It ensures that only the rightful owner of the passport can initiate this process, preserving the integrity of the system.

Responses

Response samples

Content type
application/json

Alice from Acme Corp is registering a new device.

{
  • "registration_id": "reg-123456",
  • "options": {
    }
}

Add a new device to a passport identity

Empower your digital identity by securely adding a new device to your HUMAN Passport. This endpoint ensures that only authorized devices can be associated, maintaining the integrity and security of your digital interactions.

Request Body schema: application/json
required
required
object
required
object
device_type
string

Responses

Request samples

Content type
application/json

Illustrates adding a new device with valid authorization and registration.

{
  • "authorization": {
    },
  • "new_device": {
    },
  • "device_type": "smartphone"
}

Response samples

Content type
application/json
{
  • "device_id": "device-789",
  • "added_at": "2023-10-01T12:34:56.789Z",
  • "status": "active"
}

Register new device in control plane

Orchestrate the enrollment of a new device within your organization using HUMAN's control plane. Connect devices with the HUMAN network, track their capabilities, and ensure secure task routing with the power of AI. This endpoint is crucial for maintaining seamless operations across distributed systems.

Request Body schema: application/json
required
org_did
required
string

Decentralized identifier for the organization

device_did
string

Decentralized identifier for the device

label
required
string

Human-readable label for identifying the device

fingerprint
string

Unique fingerprint for device identification

device_type
string

Type of device, e.g., 'edge', 'cloud'

capabilities
object

Capabilities this device offers as a JSON object

metadata
object

Additional metadata about the device

Responses

Request samples

Content type
application/json

Enroll a device with essential information

{
  • "org_did": "did:example:123456789abcdefghi",
  • "device_did": "did:example:abcdefghij123456789",
  • "label": "Edge Device #42",
  • "fingerprint": "abc123fingerprint",
  • "device_type": "edge",
  • "capabilities": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "device-12345",
  • "org_did": "did:example:123456789abcdefghi",
  • "device_did": "did:example:abcdefghij123456789",
  • "label": "Edge Device #42",
  • "fingerprint": "abc123fingerprint",
  • "device_type": "edge",
  • "capabilities": {
    },
  • "metadata": {
    },
  • "enrolled_by": "passport-xyz123"
}

Create and manage device connections

Unleash the potential of interconnected devices by forging new pathways between them. This endpoint allows organizations to establish logical edges between devices, weaving a network where data flows seamlessly and securely. By connecting devices, organizations can optimize operations and enhance collaboration.

Request Body schema: application/json
required
org_did
required
string

Decentralized Identifier for the organization

source_device_id
required
string

Identifier of the source device

target_device_id
required
string

Identifier of the target device

edge_type
string
Default: "data"

Type of edge connecting devices

metadata
object

Additional information about the edge

Responses

Request samples

Content type
application/json

This example establishes a data connection between two devices within the Acme organization.

{
  • "org_did": "did:haio:acme",
  • "source_device_id": "device-123",
  • "target_device_id": "device-456",
  • "edge_type": "data",
  • "metadata": {
    }
}

Response samples

Content type
application/json
null

Update health status of a device

In the intricate dance of human and AI collaboration, devices play a pivotal role. This endpoint allows devices to signal their current health status, ensuring timely intervention and seamless operations. By keeping the HUMAN ecosystem informed, we maintain the harmony essential for efficient orchestration.

Request Body schema: application/json
required
health_status
required
string
Enum: "healthy" "degraded" "error" "unknown" "offline"

The current health status of the device.

Responses

Request samples

Content type
application/json

A device signaling it's in a healthy state.

{
  • "health_status": "healthy"
}

Response samples

Content type
application/json
null

Unenroll device from organization's control plane

Remove a device from the organization's orchestration network, cascading updates throughout the system. This endpoint ensures that devices no longer required or transferred are securely and thoroughly unenrolled, maintaining system integrity and security.

Responses

Response samples

Content type
application/json

The device with ID 12345 was successfully unenrolled from the organization with DID acme:org:9876.

null

Approve device sync for a HUMAN passport

In the tapestry of the HUMAN platform, this endpoint acts as a gatekeeper, ensuring only rightful devices can sync with a user's passport. By approving a sync session, users authenticate and authorize their devices, maintaining the integrity and security of their digital identity.

Request Body schema: application/json
required
session_id
required
string

Unique identifier for the sync session

current_device_signature
required
string

JWS signature from the current device

new_device_ephemeral_public_key
required
string

Ephemeral public key for the new device

encrypted_vault_envelope
string or null

Encrypted vault envelope required in non-P2P mode

Responses

Request samples

Content type
application/json

Approving a device sync with all necessary fields

{
  • "session_id": "session12345",
  • "current_device_signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "new_device_ephemeral_public_key": "04bfcab3...abc",
  • "encrypted_vault_envelope": "e3d9a1f...f9d"
}

Response samples

Content type
application/json

Successful sync approval in P2P mode

{
  • "device_attestation": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Complete Device Sync for Passport

Securely finalize the synchronization of a new device with your HUMAN Passport, ensuring the integrity of cryptographic identity at every step. This endpoint not only validates the device's credentials but also reinforces trust through stringent attestation checks.

Request Body schema: application/json
required
session_id
required
string

Session ID for the sync process.

device_attestation
required
string

JWT for attesting the device's validity.

new_device_name
required
string <= 100 characters

A human-readable identifier for the new device.

new_device_public_key
required
string

Public key associated with the new device.

Responses

Request samples

Content type
application/json

Example of completing device sync for a new device named 'AcmeLaptop'.

{
  • "session_id": "abc123-session",
  • "device_attestation": "eyJhbGciOiJIUzI1NiIsInR...",
  • "new_device_name": "AcmeLaptop",
  • "new_device_public_key": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBA..."
}

Response samples

Content type
application/json
{
  • "device_id": "device-12345",
  • "enrolled_at": "2023-10-01T12:45:00Z"
}

Tokens

Create Personal Access Token

Generate a secure Personal Access Token (PAT) to authenticate and authorize specific capabilities on the HUMAN platform. This enables users to define scopes for their tokens, ensuring precise skill delegation and operational security.

Request Body schema: application/json
required
name
required
string

Descriptive name for the token

scopes
required
Array of strings

Array of capability URIs defining the token's permissions

expires_in
string

Duration before the token expires, e.g., '1h', '30m'

risk_level
string
Enum: "low" "standard" "high"

Risk level associated with the token

environment
string
Enum: "dev" "staging" "production"

Environment where the token is valid

Responses

Request samples

Content type
application/json

Creating a token with read-only access for development environment

{
  • "name": "Dev Read-Only Token",
  • "scopes": [
    ],
  • "expires_in": "1h",
  • "risk_level": "low",
  • "environment": "dev"
}

Response samples

Content type
application/json
{
  • "token_id": "tok_1234567890",
  • "token": "HPAT_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "name": "Dev Read-Only Token",
  • "scopes": [
    ],
  • "created_at": "2023-10-31T12:34:56Z",
  • "expires_at": "2023-10-31T13:34:56Z"
}

Retrieve API Delegation Tokens

Explore the world of digital credentials by retrieving a list of API delegation tokens tied to your cryptographic identity. This endpoint empowers organizations like 'Acme Corp' to manage and audit their delegation tokens effortlessly, ensuring secure and traceable operations in a distributed ledger environment.

Responses

Response samples

Content type
application/json

A snapshot of Acme Corp's active API delegation tokens.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at",
  • "hasMore": false
}

Retrieve tokens by delegation ID

Discover the lifeline of your delegation tokens with a simple query. This endpoint empowers you to list tokens tied to a specific delegation, ensuring precise control and oversight of token usage within the HUMAN ecosystem.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Passport

Retrieve API Delegation Tokens

Explore the world of digital credentials by retrieving a list of API delegation tokens tied to your cryptographic identity. This endpoint empowers organizations like 'Acme Corp' to manage and audit their delegation tokens effortlessly, ensuring secure and traceable operations in a distributed ledger environment.

Responses

Response samples

Content type
application/json

A snapshot of Acme Corp's active API delegation tokens.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at",
  • "hasMore": false
}

Revoke Passport Token by ID

This endpoint gracefully revokes a specific passport token, ensuring it no longer grants access or capabilities. It's crucial for maintaining the integrity and security of the HUMAN ecosystem, as it allows users to effectively manage and revoke permissions when necessary.

Responses

Response samples

Content type
application/json

Successfully revoking a passport token for an organization.

null

Retrieve Passport Holder's Activity Feed

Explore the vibrant tapestry of a passport holder's digital journey through their activity feed. This endpoint offers a glimpse into the events that shape their online interactions, ensuring that sensitive information is filtered with precision, reflecting the orchestration between human discretion and AI insight.

Responses

Response samples

Content type
application/json

The 'acme' organization views the activity feed of a passport holder detailing different event types, actors, and connectors.

{
  • "data": [
    ],
  • "hasMore": true,
  • "nextCursor": "cursor_abc123"
}

Retrieve a specific activity event

Dive into the story of a particular event within your cryptographic identity's history on the HUMAN platform. This endpoint is your gateway to verifying the authenticity and details of an activity, complete with a receipt that ensures its linkage proof. It's all about ensuring trust in every interaction.

Responses

Response samples

Content type
application/json

An example of a successfully retrieved activity event

{
  • "event_id": "evt_123456",
  • "subject_did": "did:human:acme_1234",
  • "activity_type": "DOCUMENT_SIGNED",
  • "timestamp": "2023-10-05T14:48:00Z",
  • "details": {
    },
  • "receipt": "abc123def456ghi789"
}

Retrieve Detailed Grant Information

Uncover the full potential of your grant by retrieving detailed information including scopes, constraints, and usage history. This endpoint empowers the granter to manage and review their own grants, ensuring security and transparency in capabilities sharing.

Responses

Response samples

Content type
application/json

An example response for retrieving a grant used by the Acme organization.

{
  • "grant_id": "grant123",
  • "scopes": [
    ],
  • "constraints": {
    },
  • "last_used_at": "2023-10-21T15:23:45Z"
}

Narrow scopes on a delegation grant

In the intricate dance of permissions and trust, sometimes it becomes necessary to tighten the reins. This endpoint allows an organization to refine the permissions they've granted, ensuring the recipient can only access what's truly essential. It's about maintaining control in a dynamic environment.

Request Body schema: application/json
required
scopes
required
Array of strings

A strict subset of the current scopes to narrow the delegation.

constraints
required
object

Additional conditions applied to the delegation grant.

Responses

Request samples

Content type
application/json

An example where the grant is narrowed to only include 'read:invoices' scope.

{
  • "scopes": [
    ],
  • "constraints": {
    }
}

Response samples

Content type
application/json
null

Pause an active delegation grant

In the intricate dance of human and AI collaboration, there may come a time when a delegation grant needs a pause — a momentary rest to reassess or reallocate resources. This endpoint allows you to hit that pause button, ensuring the grant remains dormant yet poised for future reactivation.

Responses

Response samples

Content type
application/json

Pausing a delegation grant for the 'acme' organization.

{
  • "delegation_id": "grant_12345",
  • "status": "paused",
  • "grantor_did": "did:human:acme"
}

Expire an active delegation grant early

In the intricate world of Human-AI collaboration, timing is everything. This endpoint allows you to shorten the expiry of an active delegation grant, ensuring that permissions are curtailed as needed. By empowering users to manage time-sensitive access, we enhance security and control.

Request Body schema: application/json
required
expires_at
required
string <date-time>

The new expiry date, which must be a valid ISO 8601 timestamp and cannot extend the current expiry.

Responses

Request samples

Content type
application/json

This example shows how to shorten the expiry of a grant to a specific future date.

{
  • "expires_at": "2023-12-31T23:59:59Z"
}

Response samples

Content type
application/json
null

Retrieve Merkle proof for event verification

Unlock the cryptographic assurance of your event's integrity with a Merkle proof. This endpoint provides the cryptographic evidence necessary to independently verify an event's presence in the ledger, championing transparency and decentralization by eliminating reliance on HUMΛN's internal databases.

Responses

Response samples

Content type
application/json

A successful retrieval of the Merkle proof for a specific event.

{
  • "event_id": "event_123456",
  • "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  • "ledger_anchor_ref": "anchor_78910",
  • "proof": {
    }
}

Register a new application with a Passport

Embark on a journey to integrate your application into the HUMAN ecosystem by registering it with a unique Passport. This endpoint establishes your application's identity, enabling it to interact securely and efficiently through HUMAN's protocol.

Request Body schema: application/json
required
app_name
required
string

The name of your application

app_type
required
string
Enum: "web" "native" "spa"

The type of application, guiding security strategies

redirect_uris
required
Array of strings <uri> [ items <uri > ]
scopes
required
Array of strings

Responses

Request samples

Content type
application/json

This example registers a web application named 'Invoicer' for managing company invoices.

{}

Response samples

Content type
application/json
null

Authorize and Consent OAuth Requests

Facilitates user consent for OAuth authorization by securely handling the exchange of authorization codes. This endpoint ensures that users' cryptographic identities and delegated capabilities are respected, maintaining a seamless and secure user experience.

Request Body schema: application/json
required
request_id
required
string

A unique identifier for the OAuth authorization request.

Responses

Request samples

Content type
application/json

A typical request for authorizing an OAuth process.

{
  • "request_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json

Redirect URL with the granted authorization code.

{}

Revoke a specific passport credential

This endpoint allows the issuing passport to revoke a credential, reflecting changes in a user's capability graph. By revoking a credential, you ensure the integrity and accuracy of the distributed ledger, protecting the ecosystem from outdated or incorrect data.

Request Body schema: application/json
required
One of
effective_date
required
string <date-time>

The ISO 8601 date-time when the revocation should take effect.

Responses

Request samples

Content type
application/json

Revoke a credential starting from January 1, 2024.

{
  • "effective_date": "2024-01-01T00:00:00Z"
}

Response samples

Content type
application/json
null

Create Verifiable Credential for Human Passport

This endpoint empowers organizations and agents to issue verifiable credentials tied to a human's digital identity. By securely managing these credentials, organizations can assert skills or qualifications that are cryptographically verifiable, enhancing trust in digital interactions.

Request Body schema: application/json
required
subject_did
required
string

The DID of the human subject receiving the credential.

issuer_did
required
string

The DID of the issuer, which must be an org or agent.

type
required
Array of strings

The type(s) of credential being issued.

claims
required
object

A JSON object representing claims associated with the credential.

expiration_date
string <date-time>

The optional expiration date for the credential in ISO 8601 format.

Responses

Request samples

Content type
application/json

Demonstrates issuing a credential asserting a skill proficiency.

{
  • "subject_did": "did:human:123456789abcdefghi",
  • "issuer_did": "did:org:acme",
  • "type": [
    ],
  • "claims": {
    },
  • "expiration_date": "2025-12-31T23:59:59Z"
}

Response samples

Content type
application/json
null

Create a Client-Signed Credential

This endpoint allows an authenticated issuer to create a client-signed credential within the HUMAN network. By leveraging cryptographic proofs, it ensures the integrity and authenticity of issued credentials, advancing trust in decentralized identity management.

Request Body schema: application/json
required
One of
subject_did
required
string^did:human:.*
issuer_did
required
string^did:human:.*
type
Array of strings
claims
required
object
issued_at
required
string <date-time>
expiration_date
string <date-time>
signature
required
string
signing_key_purpose
string
Enum: "attest" "auth"

Responses

Request samples

Content type
application/json

Example of issuing a credential for a subject with specific claims.

{
  • "subject_did": "did:human:example123",
  • "issuer_did": "did:human:issuer456",
  • "type": [
    ],
  • "claims": {
    },
  • "issued_at": "2023-10-01T12:00:00Z",
  • "expiration_date": "2024-10-01T12:00:00Z",
  • "signature": "base64encodedsignature==",
  • "signing_key_purpose": "attest"
}

Response samples

Content type
application/json

A credential issued for a software engineer at Acme Corp.

{
  • "credential_id": "cred-abcdef123456",
  • "type": [
    ],
  • "issued_at": "2023-10-01T12:00:00Z",
  • "proof": {
    },
  • "ledger_anchor": {
    }
}

Add a new device to a passport identity

Empower your digital identity by securely adding a new device to your HUMAN Passport. This endpoint ensures that only authorized devices can be associated, maintaining the integrity and security of your digital interactions.

Request Body schema: application/json
required
required
object
required
object
device_type
string

Responses

Request samples

Content type
application/json

Illustrates adding a new device with valid authorization and registration.

{
  • "authorization": {
    },
  • "new_device": {
    },
  • "device_type": "smartphone"
}

Response samples

Content type
application/json
{
  • "device_id": "device-789",
  • "added_at": "2023-10-01T12:34:56.789Z",
  • "status": "active"
}

Retrieve a user’s cryptographic identity

Delve into the realm of digital authenticity by fetching a user’s cryptographic identity from the HUMAN ecosystem. This endpoint allows authenticated users to explore their unique digital footprint, encapsulating their identity and associated devices, ensuring a seamless blend of privacy and transparency.

Responses

Response samples

Content type
application/json

Retrieving John's digital passport details, including active devices and credential counts.

{
  • "did": "did:human:123456789abcdef",
  • "display_name": "John Doe",
  • "person_type": "individual",
  • "created_at": "2023-01-15T12:34:56Z",
  • "is_active": true,
  • "credential_count": 3,
  • "devices": [
    ]
}

Create a New Cryptographic Identity

Embark on a journey to establish a cryptographic identity through our Passport system, enabling secure and verifiable interactions within the HUMAN platform. This endpoint orchestrates the identity creation process with idempotent guarantees ensuring consistent outcomes.

Responses

Response samples

Content type
application/json

A successful response showing the newly created identity and its enrollment data.

{
  • "id": "identity-12345",
  • "enrollmentData": {
    }
}

Request WebAuthn Options for Disclosure

Unlock the potential of secure identity verification by requesting WebAuthn options for a pending disclosure. This endpoint ensures that only the valid subject of a disclosure request can initiate the WebAuthn process, thus preserving the integrity and security of the HUMAN protocol.

Responses

Response samples

Content type
application/json

An example where a subject successfully retrieves WebAuthn options for a pending disclosure request.

{
  • "challenge_id": "5f8d04b3-8d3d-4c2a-8a9e-1234567890ab",
  • "options": {
    }
}

Grant Passport Disclosure Request

Empower digital identities by granting disclosure requests through secure WebAuthn verification. This endpoint ensures that only authorized parties can disclose sensitive attributes, maintaining the integrity and trust within the HUMAN platform.

Request Body schema: application/json
required
required
object
required
Array of objects

A list of attributes that the subject is granting.

denied_attributes
Array of strings

A list of attributes that the subject is denying.

Responses

Request samples

Content type
application/json

Demonstrates granting disclosure with valid WebAuthn and attributes.

{
  • "webauthn": {
    },
  • "granted_attributes": [
    ],
  • "denied_attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "request_id": "request123",
  • "status": "granted",
  • "granted_at": "2023-10-05T14:48:00.000Z",
  • "disclosure_token": "pdt_exampletoken",
  • "expires_at": "2023-10-06T14:48:00.000Z"
}

Retrieve Passport Consent Records

Dive into the chronicles of your digital identity by exploring the consents associated with your Passport. This endpoint empowers you to audit the permissions granted to various agents, ensuring transparency and control over your digital footprint.

Responses

Response samples

Content type
application/json
{
  • "consents": [
    ],
  • "limit": 10,
  • "cursor": "eyJncmFudGVkX2F0IjogIjIwMjMtMTAtMDFUMTA6MDA6MDBaIiwgImNvbnNlbnRfaWQiOiAiYzFmM2VlYjQtMTJhZi00ZTlkLWE2NTQtNGYwYTdiNGMzYzhkIn0=",
  • "total": 1
}

Register a webhook for passport events

In a world where human and AI collaboration is key, webhooks allow organizations to seamlessly integrate and respond to passport events in real-time. This endpoint empowers you to subscribe to specific events, ensuring your systems are always in sync with the latest happenings.

Request Body schema: application/json
required
url
required
string

Target URL for the webhook (must use http or https).

secret
required
string

Secret for HMAC signing of webhook payloads (min 8 characters).

events
required
Array of strings

Array of passport event names to subscribe to.

Responses

Request samples

Content type
application/json

Setting up a webhook for Acme Corporation to listen to passport creation and update events.

{}

Response samples

Content type
application/json
{
  • "webhook_id": "webhook-1234",
  • "subscription_ids": [
    ],
  • "url": "https://webhooks.acme.com/passport",
  • "events": [
    ],
  • "signing_secret_stored": true
}

Create a new credential attestation

Forge a verifiable link between an organization and a subject through cryptographic identity. This endpoint empowers organizations to attest to credentials, securely embedding trust into decentralized interactions. By weaving human intent with machine precision, it strengthens the backbone of the HUMAN network.

Request Body schema: application/json
required
subject_did
required
string

Decentralized Identifier (DID) of the subject receiving the credential.

object

Additional attributes to include in the attestation payload.

Responses

Request samples

Content type
application/json

Attesting a credential for Alice under the organization 'acme'.

{
  • "subject_did": "did:example:alice",
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "attestation_id": "cp_att_cred_12345",
  • "attestation_kind": "credential",
  • "subject_did": "did:example:alice",
  • "created_at": "2023-10-22T14:48:00Z"
}

Create license attestation for a Passport

This endpoint allows organizations to attest a license to a subject's Passport, strengthening trust in identity verification within the HUMAN ecosystem. By enabling license attestations, organizations can securely affirm the skills and credentials of individuals, enhancing the reliability of the Capability Graph.

Request Body schema: application/json
required
subject_did
required
string

The decentralized identifier (DID) of the subject to whom the license is being attested

required
object

Additional metadata describing the license

Responses

Request samples

Content type
application/json

Attesting a driver's license for a subject.

{
  • "subject_did": "did:human:123456789abcdefghi",
  • "license_details": {
    }
}

Response samples

Content type
application/json
null

Retrieve Passport Jurisdiction Proofs

Unravel the cryptographic tapestry of identity by accessing jurisdiction-specific proofs associated with a Passport DID. This endpoint empowers organizations to verify identity assertions across borders, ensuring trust and compliance in human-AI orchestration.

Responses

Response samples

Content type
application/json

This example shows proofs retrieved for ACME Corp under the jurisdiction of 'US'.

{
  • "jurisdiction": "US",
  • "passport_did": "did:human:123456789abcdefghi",
  • "proofs": [
    ]
}

Record Passport Travel Context

Embark on a journey of seamless orchestration between humans and AI. This endpoint securely logs the travel context of a Passport within an organization, ensuring that each step is accounted for with precision and trust.

Request Body schema: application/json
required
passport_did
required
string

The decentralized identifier for the Passport

object

Additional context data related to the travel

Responses

Request samples

Content type
application/json

Record context for a Passport traveling to Acme Corporation's headquarters.

{
  • "passport_did": "did:example:123456789abcdefghi",
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "context_id": "cp_travel_001",
  • "passport_did": "did:example:123456789abcdefghi",
  • "recorded_at": "2023-10-01T12:00:00Z"
}

Whitelist merchants for passport interactions

Enlist merchants to interact with a passport holder, ensuring trusted exchanges within the HUMAN ecosystem. This process empowers organizations to manage merchant relationships securely and efficiently, leveraging cryptographic identities.

Request Body schema: application/json
required
passport_did
required
string

Decentralized Identifier for the passport holder

merchant_id
required
string

Unique identifier for the merchant

Responses

Request samples

Content type
application/json

An example of whitelisting a merchant for a passport holder

{
  • "passport_did": "did:human:123456789abcdefghi",
  • "merchant_id": "merchant_987654321"
}

Response samples

Content type
application/json
null

Approve recovery request as guardian

This endpoint empowers guardians to affirm their role in the recovery process, crucial for securing cryptographic identities within the HUMAN platform. By approving a recovery request, guardians help ensure that only authorized users can reclaim their digital identities, safeguarding against unauthorized access or loss.

Request Body schema: application/json
required
shard_b64
string

Plaintext shard in base64url encoding, required in SSS mode.

signature
string

Optional signature for audit trail in attestation mode.

Responses

Request samples

Content type
application/json
Example

Guardian approving with a plaintext shard in SSS mode.

{
  • "shard_b64": "c2hhcmRTYW1wbGU"
}

Response samples

Content type
application/json

A guardian's approval has been successfully processed.

{
  • "request_id": "req_12345",
  • "approvals_received": 3,
  • "approvals_required": 5,
  • "threshold_met": false,
  • "lock_until": "2023-12-31T12:00:00Z",
  • "ready_to_complete": false
}

Initiate WebAuthn registration for human passports

This endpoint orchestrates the creation of WebAuthn options, a critical step in human passport registration. It ensures a secure and verified identity by leveraging advanced cryptographic techniques, making sure only human entities can proceed. This process stands as a gatekeeper, safeguarding the integrity of the HUMAN platform's ecosystem.

Request Body schema: application/json
required
One of
display_name
required
string

User's display name for the WebAuthn registration process

person_type
required
string
Value: "Human"

Type of person, must be 'Human' for this registration

Responses

Request samples

Content type
application/json

A typical registration request for a human passport

{
  • "display_name": "Alice Doe",
  • "person_type": "Human"
}

Response samples

Content type
application/json
{
  • "registration_id": "reg_12345678",
  • "options": {
    }
}

Retrieve detailed passport information

This endpoint unveils the cryptographic identity encapsulated within a passport, serving the dual purpose of identity verification and skill tracking in the HUMAN ecosystem. It caters to diverse identities, from humans to organizations and agents, each with its own unique narrative, ensuring a seamless interplay between identity and capability.

Responses

Response samples

Content type
application/json

Retrieving a human's passport with detailed identity verification.

{
  • "passport_id": "did:human:123456789abcdefghi",
  • "did": "did:human:123456789abcdefghi",
  • "type": "Human",
  • "name": "Jane Doe",
  • "public_key": "abcdef1234567890",
  • "did_document": {
    },
  • "created_at": "2023-10-05T12:34:56Z",
  • "updated_at": "2023-10-10T15:00:00Z",
  • "vault_endpoint": "https://vault.human-protocol.org/v1/jane",
  • "vault_kdf_salt": "s0m3s4lt",
  • "avatar_url": "https://avatars.human-protocol.org/jane.jpg",
  • "preferred_language": "en"
}

Execute a Passport Recovery Request

When human and AI collide, passports need recovery. Execute an approved recovery request to breathe life back into your digital identity. This endpoint ensures seamless recovery, verifying security at each step, and offers a second chance for your cryptographic identity.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json

An example WebAuthn payload for human recovery

{
  • "webauthn": {
    }
}

Response samples

Content type
application/json
{
  • "passport_id": "did:example:123456789abcdefghi",
  • "status": "executed",
  • "next_step": "recovery_complete",
  • "auth_key_id": "key-12345",
  • "attest_key_id": "key-67890",
  • "retired_at": "2023-10-15T14:48:00.000Z"
}

Retrieve passport's attestations

Unearth the verified skills and credentials linked to a passport within the HUMAN platform. This endpoint empowers users to view the attestations tied to a cryptographic identity, revealing the journey and trustworthiness of the passport holder.

Responses

Response samples

Content type
application/json

Retrieve a list of active attestations for a specific passport, demonstrating the credentials issued by various entities.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Retrieve organization's proposal list with pagination

Explore the dynamic landscape of organizational progress by retrieving a list of proposals associated with a decentralized identifier (DID). This endpoint empowers organizations to track proposed changes, ensuring informed decision-making and transparent governance.

Responses

Response samples

Content type
application/json

A paginated response showing the first page of proposals for the 'acme' organization.

{
  • "data": [
    ],
  • "pagination": {
    }
}

Approve Organization Proposal

Navigate the intricate dance of consensus within the HUMAN network by approving proposals that shape the future of your organization. This endpoint not only records an approval but auto-executes the proposal once the required threshold is met, embedding the decision into the immutable ledger of provenance.

Request Body schema: application/json
required
One of
approver_did
required
string^did:human:.*$

Decentralized Identifier of the approver.

signature
required
string

Base64 encoded Ed25519 signature over the proposal payload.

Responses

Request samples

Content type
application/json

An example of a founder approving a proposal.

{
  • "approver_did": "did:human:founder123",
  • "signature": "dGVzdFNpZ25hdHVyZQ=="
}

Response samples

Content type
application/json
null

Dissolve an organizational passport

This endpoint initiates the irreversible dissolution of an organization's passport, signaling the end of its active status. By doing so, it ensures that all active agent delegations are revoked, safeguarding the integrity of the system. Whether asynchronously proposed for quorum approval or executed synchronously with signatures, this process is critical to maintaining a secure and trustworthy Human-AI orchestration.

Request Body schema: application/json
required
proposed_by
required
string^did:human:.*$

The DID of the proposing founder.

mode
string
Default: "async"
Enum: "async" "synchronous"

Mode of dissolution; defaults to async requiring quorum approval.

Array of objects

Required for synchronous mode. An array of cryptographic signatures from founders.

reason
string

Optional reason for dissolution proposal.

signature
string

Optional initial founder signature for async proposal.

Responses

Request samples

Content type
application/json
Example

Creating a dissolution proposal asynchronously with a reason.

{
  • "proposed_by": "did:human:12345",
  • "mode": "async",
  • "reason": "Strategic shift in organizational focus."
}

Response samples

Content type
application/json
{
  • "org_did": "did:human:org123",
  • "status": "dissolved",
  • "agents_revoked": 15,
  • "provenance_id": "prov_abc123",
  • "dissolved_at": "2023-11-01T12:34:56Z"
}

Grant Disclosure on Human Passport

Enable trusted sharing of verified capabilities by granting disclosure requests on a Human Passport. This endpoint empowers users to selectively share their validated skills, ensuring transparency and trust in Human-AI collaborations.

Request Body schema: application/json
required
approved_claims
required
Array of strings

List of claims approved for disclosure.

Responses

Request samples

Content type
application/json

A user approves specific claims for an organization.

{
  • "approved_claims": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "Disclosure granted",
  • "granted_claims": [
    ]
}

Approve device sync for a HUMAN passport

In the tapestry of the HUMAN platform, this endpoint acts as a gatekeeper, ensuring only rightful devices can sync with a user's passport. By approving a sync session, users authenticate and authorize their devices, maintaining the integrity and security of their digital identity.

Request Body schema: application/json
required
session_id
required
string

Unique identifier for the sync session

current_device_signature
required
string

JWS signature from the current device

new_device_ephemeral_public_key
required
string

Ephemeral public key for the new device

encrypted_vault_envelope
string or null

Encrypted vault envelope required in non-P2P mode

Responses

Request samples

Content type
application/json

Approving a device sync with all necessary fields

{
  • "session_id": "session12345",
  • "current_device_signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "new_device_ephemeral_public_key": "04bfcab3...abc",
  • "encrypted_vault_envelope": "e3d9a1f...f9d"
}

Response samples

Content type
application/json

Successful sync approval in P2P mode

{
  • "device_attestation": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Retrieve Passport Disclosure Details

Unearth the cryptographic secrets of a Passport with this endpoint, which reveals the story behind a specific disclosure request. This endpoint is your key to understanding the intricate dance of data between a subject and requester, spotlighting the purpose, status, and cryptographic proofs involved.

Responses

Response samples

Content type
application/json

A successful retrieval of a disclosure request for a Passport, with all cryptographic details included.

{
  • "request_id": "12345",
  • "subject_did": "did:human:acme:john.doe",
  • "requester_did": "did:human:acme:trusted.partner",
  • "requested_claims": [
    ],
  • "purpose": "Verification of identity for onboarding",
  • "status": "granted",
  • "created_at": "2023-10-05T12:34:56Z",
  • "expires_at": "2023-12-31T23:59:59Z",
  • "resolved_at": "2023-10-10T14:22:01Z",
  • "proof_type": "bbs",
  • "bbs_credential": {
    },
  • "verifier_challenge": "challenge_string",
  • "disclosed_claims": [
    ]
}

Submit Shard for Guardian Recovery

Embark on a journey of digital resurrection as you submit the vital cryptographic shard needed for recovering a lost device. This endpoint ensures that the guardians of your identity unite to restore access, maintaining the sanctity of your cryptographic Passport.

Request Body schema: application/json
required
proof_of_reconstruction
required
string

Proof that the shards have been correctly reassembled

new_device_public_key
required
string

Public key of the new device being registered

registration_id
required
string

Registration identifier for the new device

required
object

Credential object or WebAuthn attestation

object

WebAuthn attestation details, alternative to credential

Responses

Request samples

Content type
application/json

A valid submission with all required fields

{
  • "proof_of_reconstruction": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "new_device_public_key": "04bfcab2f53a...",
  • "registration_id": "reg-12345",
  • "credential": {
    }
}

Response samples

Content type
application/json
{
  • "status": "Recovery process initiated successfully"
}

Retrieve Passport Recovery Shard Signals

In a world where identity recovery is paramount, this endpoint empowers the passport holder to retrieve shard signals vital for reconstructing their cryptographic identity. It ensures the safe delivery of pending ciphertext payloads, marking them as received.

Responses

Response samples

Content type
application/json

Shows a successful retrieval of shard signals.

{
  • "request_id": "req-123456789",
  • "signals": [
    ]
}

Create a Consent Policy for a Passport

This endpoint allows a passport holder to define consent policies that dictate how their data can be accessed. By automating approval or denial of specific claims, users maintain control over their digital identity while reducing manual intervention.

Request Body schema: application/json
required
claim_names
required
Array of strings

A non-empty array of claims that this policy applies to

action
required
string
Enum: "auto_approve" "auto_deny"

The action to take when the claims match this policy

requester_did_pattern
string

An optional pattern to match requesters by their DID

purpose_pattern
string

An optional pattern describing the purpose context

priority
integer

The priority of this policy, with lower numbers indicating higher priority

Responses

Request samples

Content type
application/json

Creates a policy to auto-approve access for specific claims

{
  • "claim_names": [
    ],
  • "action": "auto_approve",
  • "requester_did_pattern": "did:human:org:test",
  • "purpose_pattern": "data:access",
  • "priority": 50
}

Response samples

Content type
application/json
{
  • "id": "policy-123",
  • "passport_did": "did:human:example:123456",
  • "requester_did_pattern": "did:human:org:test",
  • "claim_names": [
    ],
  • "purpose_pattern": "data:access",
  • "action": "auto_approve",
  • "priority": 50,
  • "created_at": "2023-10-01T12:34:56Z"
}

Retrieve consent policies for a passport

Dive into the intricate world of consent management with HUMAN's Passport Consent Policies. This endpoint allows you to explore the nuanced policies that govern what claims and actions are automatically approved or denied for a specific passport. Empowering users and organizations, it ensures transparency and control over data sharing.

Responses

Response samples

Content type
application/json

Acme Corp is reviewing its consent policies for compliance and data governance.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Retrieve evidence linked to a Passport

Delve into the rich tapestry of evidence associated with a given Passport. This endpoint empowers you to explore and filter evidence by class, strength, state, and outcome — revealing the provenance behind decisions and interactions within the HUMAN network.

Responses

Response samples

Content type
application/json

A list of evidence items for a specific Passport.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "id",
  • "hasMore": false
}

Retrieve active capabilities for a Passport DID

Uncover the skills and capabilities associated with a given Passport's DID. This endpoint helps you understand the active capabilities granted to an AI or human agent, providing insight into their skillset within the HUMAN platform.

Responses

Response samples

Content type
application/json

An example showing the retrieval of active capabilities for a given DID.

{
  • "passport_did": "did:human:1234abcd",
  • "grant_count": 2,
  • "grants": [
    ]
}

Activity

Retrieve Passport Holder's Activity Feed

Explore the vibrant tapestry of a passport holder's digital journey through their activity feed. This endpoint offers a glimpse into the events that shape their online interactions, ensuring that sensitive information is filtered with precision, reflecting the orchestration between human discretion and AI insight.

Responses

Response samples

Content type
application/json

The 'acme' organization views the activity feed of a passport holder detailing different event types, actors, and connectors.

{
  • "data": [
    ],
  • "hasMore": true,
  • "nextCursor": "cursor_abc123"
}

Retrieve a specific activity event

Dive into the story of a particular event within your cryptographic identity's history on the HUMAN platform. This endpoint is your gateway to verifying the authenticity and details of an activity, complete with a receipt that ensures its linkage proof. It's all about ensuring trust in every interaction.

Responses

Response samples

Content type
application/json

An example of a successfully retrieved activity event

{
  • "event_id": "evt_123456",
  • "subject_did": "did:human:acme_1234",
  • "activity_type": "DOCUMENT_SIGNED",
  • "timestamp": "2023-10-05T14:48:00Z",
  • "details": {
    },
  • "receipt": "abc123def456ghi789"
}

IdentityManagement

Retrieve Delegation Token Details

Uncover the secrets of delegation by fetching detailed information about a specific delegation token. This endpoint empowers you to navigate the intricacies of digital identity and access control, ensuring that every interaction is securely tracked and validated through the HUMAN platform.

Responses

Response samples

Content type
application/json
{
  • "delegation_id": "del_123456",
  • "token_id": "tok_78910",
  • "scope": [
    ],
  • "expires_at": "2023-12-31T23:59:59Z",
  • "created_at": "2023-01-01T00:00:00Z",
  • "last_used_at": "2023-09-15T12:34:56Z",
  • "revoked_at": null
}

Delegations

Retrieve Delegation Revocation Status

Explore the intricate dance of permissions and trust with this endpoint, which reveals whether a delegation has been revoked. In the world of HUMAN's decentralized networks, knowing the status of delegations is crucial for maintaining the integrity of operations and ensuring the right agents hold the right capabilities.

Responses

Response samples

Content type
application/json
Example
{
  • "revoked": true,
  • "revoked_at": "2023-10-03T14:48:00Z",
  • "revoked_reason": "Violation of terms"
}

Retrieve List of Revoked Delegations

Explore the tapestry of revoked delegations to understand the nuances of permission changes over time. This endpoint serves as a historical ledger, providing a window into what was once granted and no longer stands, aiding in auditing and compliance efforts.

Responses

Response samples

Content type
application/json

An example of successfully retrieving a page of revoked delegations.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Retrieve the status of a delegation

In the realm of Human-AI orchestration, understanding the status of a delegation is crucial for seamless task execution. This endpoint allows you to verify whether a delegation is active, revoked, or expired, ensuring optimal alignment between human and AI capabilities. It exists to safeguard against unauthorized actions and maintain integrity within the HUMAN ecosystem.

Responses

Response samples

Content type
application/json
Example

A delegation that is currently active.

{
  • "delegation_id": "d1234",
  • "status": "active"
}

Retrieve delegation grants for a passport

Explore the cryptographic relationships that bind humans and AI by retrieving delegation grants for your authenticated passport. This endpoint allows you to track the web of trust and capabilities extended and received, helping to ensure that every interaction is secure and verifiable.

Responses

Response samples

Content type
application/json

Retrieve active delegation grants, showcasing the permissions Acme Corp has granted to various agents.

{
  • "data": [
    ],
  • "limit": 20,
  • "hasMore": false
}

Revocations

Retrieve Delegation Revocation Status

Explore the intricate dance of permissions and trust with this endpoint, which reveals whether a delegation has been revoked. In the world of HUMAN's decentralized networks, knowing the status of delegations is crucial for maintaining the integrity of operations and ensuring the right agents hold the right capabilities.

Responses

Response samples

Content type
application/json
Example
{
  • "revoked": true,
  • "revoked_at": "2023-10-03T14:48:00Z",
  • "revoked_reason": "Violation of terms"
}

Retrieve List of Revoked Delegations

Explore the tapestry of revoked delegations to understand the nuances of permission changes over time. This endpoint serves as a historical ledger, providing a window into what was once granted and no longer stands, aiding in auditing and compliance efforts.

Responses

Response samples

Content type
application/json

An example of successfully retrieving a page of revoked delegations.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Authorization

Retrieve active session permissions

Discover the rights and capabilities granted to your current session, ensuring you can navigate the HUMAN platform with confidence and clarity. By understanding your permissions, you can seamlessly orchestrate tasks, knowing what actions are at your disposal.

Responses

Response samples

Content type
application/json

An example showing successful retrieval of permissions for an active session.

{
  • "permissions": [
    ],
  • "delegation_id": "abc123",
  • "expires_at": "2023-11-30T15:00:00Z"
}

Authorize billing overage for an organization

Unlock additional billing capacity beyond preset limits with this endpoint, ensuring your organization never hits a processing ceiling. It's designed for those moments when unexpected demand is a sign of success, not a bottleneck.

Request Body schema: application/json
required
amount_usd
required
number [ 0.01 .. 10000 ]

The amount in USD to authorize for overage.

window_minutes
number [ 1 .. 1440 ]

The validity duration of the authorization in minutes.

auto_topup
boolean

If true, enables automatic top-up when balance is low.

Responses

Request samples

Content type
application/json

An example where the organization authorizes a $500 overage for 120 minutes with auto top-up enabled.

{
  • "amount_usd": 500,
  • "window_minutes": 120,
  • "auto_topup": true
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "org_did": "did:org:acme",
  • "authorized_topup_usd": 500,
  • "auto_topup_enabled": true,
  • "expires_at": "2023-10-23T16:00:00Z"
}

Retrieve User Contexts for Delegated Access

This endpoint reveals the rich tapestry of organizational contexts a human agent operates within. By leveraging delegation, it ensures users can seamlessly access the ecosystems they're part of, empowering decisions with appropriate authority and insight.

Responses

Response samples

Content type
application/json

Retrieve contexts for a user with access to multiple organizations

{
  • "data": [
    ]
}

Session Management

Retrieve active session permissions

Discover the rights and capabilities granted to your current session, ensuring you can navigate the HUMAN platform with confidence and clarity. By understanding your permissions, you can seamlessly orchestrate tasks, knowing what actions are at your disposal.

Responses

Response samples

Content type
application/json

An example showing successful retrieval of permissions for an active session.

{
  • "permissions": [
    ],
  • "delegation_id": "abc123",
  • "expires_at": "2023-11-30T15:00:00Z"
}

Initiate a Duplex Session for Interaction

Begin an interactive session where human and AI collaborate seamlessly. This endpoint is the gateway to orchestrating dynamic conversations, ensuring that tasks are handled with precision and AI safety. Dive into a world where your AI can act as a passive observer, a collaborative coach, or take the reins as an active participant.

Request Body schema: application/json
required
mode
required
string
Enum: "passive" "coach" "active"

The operational mode of the session.

agent_id
string

Unique identifier for the agent initiating the session.

provider
string

Specifies the service provider for the session.

persona_id
string

Identifier for the persona to be used.

privacy_profile_id
string

Identifier for the privacy profile to be used.

org_id
string

Identifier for the organization under which the session is being initiated.

Responses

Request samples

Content type
application/json

Initiates a session with the AI in passive mode.

{
  • "mode": "passive",
  • "agent_id": "agent_007",
  • "provider": "acme_voice_service",
  • "persona_id": "support_bot",
  • "privacy_profile_id": "confidential",
  • "org_id": "acme_corp"
}

Response samples

Content type
application/json
{
  • "session_id": "sess_12345",
  • "mode": "passive",
  • "provider": "acme_voice_service",
  • "status": "active",
  • "created_at": "2023-10-01T12:34:56Z"
}

Pause a live duplex session

In the bustling world of human-AI interaction, sometimes you need a breather. This endpoint lets you pause an ongoing duplex session, providing control and flexibility in managing real-time exchanges. Whether you're handling a complex negotiation or need a moment to regroup, this functionality ensures you can pause without missing a beat.

Request Body schema: application/json
required
session_id
required
string

Unique identifier for the duplex session to pause.

Responses

Request samples

Content type
application/json

Pausing a session with ID '123e4567-e89b-12d3-a456-426614174000'.

{
  • "session_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
null

Resume an existing duplex session

In the dynamic world of human-AI collaboration, the ability to pause and resume interactions is essential. This endpoint breathes life back into a paused duplex session, allowing humans and AI to seamlessly continue their orchestration journey. By reactivating a session, we ensure that no valuable interaction goes unfinished.

Responses

Response samples

Content type
application/json
null

Revoke an MCP session by ID

In the ever-evolving landscape of AI-driven tasks, sessions are the lifeline of task processing. This endpoint allows authorized users to revoke a session, ensuring that outdated or unauthorized sessions don't linger, maintaining the integrity and security of our Human-AI orchestration.

Responses

Response samples

Content type
application/json
null

Retrieve Companion Session Details

Uncover the details of your current Companion session, revealing the cryptographic identity and active interactions. This endpoint is essential for organizations to manage their AI and human collaboration securely.

Responses

Response samples

Content type
application/json
{
  • "companion_agent_did": "did:human:agent:1234567890abcdef",
  • "org_did": "did:human:org:acme-corp",
  • "passport_did": "did:human:passport:user123",
  • "active_subscriptions_count": 5
}

Provenance

Retrieve Provenance Graph by Workflow

Dive into the journey of a workflow within the HUMAN protocol. This endpoint unveils the intricate web of tasks and decisions that form a workflow's provenance, ensuring transparency and accountability.

Responses

Response samples

Content type
application/json

The provenance graph for Acme's invoice processing workflow.

{
  • "workflow_id": "workflow-12345",
  • "graph": {
    },
  • "root_node_id": "node-1",
  • "terminal_node_id": "node-5",
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-01T12:10:00Z"
}

Query Provenance Records with Filters

Uncover the history behind your data by querying provenance records with precision. This endpoint empowers you to trace the lineage of actions within your organization, filtering by specific actors, events, or timeframes. Dive deep into the Distributed Ledger to ensure transparency and accountability.

Request Body schema: application/json
required
object
query
string

Optional query string for advanced search

Responses

Request samples

Content type
application/json

Query provenance records for a specific organization and actor

{
  • "filters": {
    },
  • "query": "status:completed"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Attest Provenance Event for Verification

In the intricate dance of information and identity, this endpoint allows trusted parties to attest to the authenticity of a provenance event. By doing so, it ensures the integrity and trustworthiness of the data within the HUMAN ecosystem, binding the present to the verified past.

Request Body schema: application/json
required
org_did
string

Decentralized identifier for the organization.

provenance_record_id
required
string

Unique identifier for the provenance record.

object

Optional payload to include additional metadata for attestation.

Responses

Request samples

Content type
application/json

Attest a provenance record for the 'acme' organization.

{
  • "org_did": "did:human:acme123",
  • "provenance_record_id": "prov-456def789",
  • "attestation_payload": {
    }
}

Response samples

Content type
application/json
null

Log Fraud Decision for Provenance Tracking

In the delicate dance of fraud detection, ensuring the authenticity of decisions is paramount. This endpoint records fraud decisions into the HUMAN Distributed Ledger, providing an immutable provenance trail. By capturing these decisions, organizations can maintain transparency and accountability in their fraud detection processes.

Request Body schema: application/json
required
case_ref
required
string

Reference ID of the fraud case.

decision_type
string
Default: "fraud_decision"

Type of decision made regarding the case.

Responses

Request samples

Content type
application/json

Logs a decision for a potential fraud case.

{
  • "case_ref": "INV-12345",
  • "decision_type": "fraudulent"
}

Response samples

Content type
application/json
{
  • "provenance_entry_id": "cp_fprov_67890",
  • "case_ref": "INV-12345",
  • "decision_type": "fraudulent",
  • "recorded_at": "2023-10-01T12:00:00Z"
}

Stream Provenance Events via SSE

Dive into the heartbeat of your organization with a real-time stream of provenance events. This endpoint exists to ensure transparency and traceability, allowing you to monitor the flow of data and actions within your systems as they happen. Embrace the power of live data and make informed decisions with every beat.

Responses

Response samples

Content type
application/json

A continuous stream of events for an organization monitoring data provenance.

"event: event\ndata: {\"event_id\": \"evt-1234\", \"event_type\": \"data_update\", \"created_at\": \"2023-10-01T12:00:00Z\", \"org_did\": \"did:example:acme-org\"}\n\n"

Retrieve detailed event information

This endpoint unlocks the story behind an event by fetching its comprehensive details using its unique identifier. It's designed to ensure that organizations can trace back any event within their operations, maintaining a seamless record of activities with accountability and transparency.

Responses

Response samples

Content type
application/json

An event detailing the processing of an invoice by Acme Corporation.

{
  • "eventId": "evt-12345",
  • "orgDid": "did:example:acme123",
  • "timestamp": "2023-10-05T14:48:00.000Z",
  • "details": "Invoice INV-001 processed successfully."
}

Retrieve execution provenance graph

Dive into the intricate web of task execution with our provenance graph. By querying this endpoint, you uncover the nodes and edges that outline the path your execution traversed. This transparency is not just for oversight but also for insights, enabling you to optimize workflows and trace the lineage of your data processes.

Responses

Response samples

Content type
application/json

Shows the provenance graph for an invoice processing execution at Acme Org.

{
  • "execution_id": "123e4567-e89b-12d3-a456-426614174000",
  • "nodes": [
    ],
  • "edges": [
    ]
}

Retrieve provenance for artifact

Uncover the journey of an artifact within the HUMAN ecosystem. This endpoint allows organizations to trace the provenance of their artifacts, providing an insightful look into its history and transformations, ensuring transparency and fraud prevention.

Responses

Response samples

Content type
application/json

An example response showing the provenance of an artifact.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Verify the provenance of an artifact

Unravel the intricate history of your digital artifacts with our provenance verification. This endpoint allows organizations to validate the integrity and authenticity of their artifacts by checking their provenance hashes, ensuring trust and transparency in the HUMAN platform.

Responses

Response samples

Content type
application/json
{
  • "artifact_id": "123e4567-e89b-12d3-a456-426614174000",
  • "verified": true,
  • "message": "Provenance verified successfully."
}

Retrieve task provenance details

Explore the intricate journey of a task within the HUMAN ecosystem through its provenance data. This endpoint weaves a narrative of how tasks evolve, ensuring transparency and accountability in AI-human collaboration.

Responses

Response samples

Content type
application/json

Fetching the provenance details for task A1 belonging to org acme.

{
  • "routing_id": "1234-5678-9012",
  • "task_id": "acme:task-a1",
  • "routing_summary": {
    },
  • "pipeline_stages": {
    },
  • "provenance_graph": {
    }
}

Retrieve decision audit chain details

Explore the intricate web of decisions with this endpoint, which unveils the comprehensive audit trail of a specific decision. By fetching the materialized decision chain, organizations can ensure accountability and transparency in their decision-making processes, paving the way for improved governance and trust.

Responses

Response samples

Content type
application/json
{
  • "decision": {
    },
  • "events": [
    ]
}

Retrieve structured decision explanation

Unlock the story behind a decision with detailed provenance and routing signals. This endpoint offers a deep dive into the decision-making process, providing insights into the integrity and policy conformance of AI-augmented human actions.

Responses

Response samples

Content type
application/json

An example showing decision explanation for an AI decision.

{
  • "decision_id": "dec123",
  • "summary": "AI decision for invoice processing",
  • "policy_version_snapshot": "v2023.10",
  • "escalation_occurred": false,
  • "override_occurred": true,
  • "integrity_status": "verified",
  • "routing_signals": [
    ],
  • "citations": [
    ]
}

Retrieve Audit Decision Chain Details

Uncover the provenance of decisions by exploring their audit trail within the HUMAN ecosystem. This endpoint serves as a gateway to transparency, allowing organizations to verify the integrity and source of decisions made by their systems.

Responses

Response samples

Content type
application/json

An organization retrieves the chain details of a decision to audit its origin and verify its integrity.

{
  • "decision_id": "123e4567-e89b-12d3-a456-426614174000",
  • "provenance_chain_id": "chain-abc123",
  • "source_event_hashes": [
    ],
  • "chain_integrity": "b1946ac92492d2347c6235b4d2611184"
}

Retrieve detailed evidence record

This endpoint unveils the story behind an evidence record by fetching its details and lifecycle events. It plays a crucial role in understanding the provenance and integrity of an evidence item, ensuring transparency and accountability within the HUMAN platform.

Responses

Response samples

Content type
application/json

Example of a successful retrieval of an evidence record for an invoice processing task.

{
  • "evidence_record": {
    },
  • "evidence_lifecycle_events": [
    ]
}

Workflows

Retrieve Provenance Graph by Workflow

Dive into the journey of a workflow within the HUMAN protocol. This endpoint unveils the intricate web of tasks and decisions that form a workflow's provenance, ensuring transparency and accountability.

Responses

Response samples

Content type
application/json

The provenance graph for Acme's invoice processing workflow.

{
  • "workflow_id": "workflow-12345",
  • "graph": {
    },
  • "root_node_id": "node-1",
  • "terminal_node_id": "node-5",
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-01T12:10:00Z"
}

Retrieve Workflow DAG Visual Representation

Uncover the intricate dance of tasks with a detailed Directed Acyclic Graph (DAG) for a specified workflow. This endpoint empowers users to visualize workflow orchestration, aiding in understanding complex task dependencies and execution flows.

Responses

Response samples

Content type
application/json
{
  • "workflow_id": "workflow-123",
  • "nodes": [
    ],
  • "edges": [
    ],
  • "stats": {
    }
}

Retrieve workflow execution statistics

Unlock insights into your workflows with detailed statistics. This endpoint is your gateway to understanding execution patterns, helping you optimize for efficiency and reliability. Discover the story behind every node in your workflow.

Responses

Response samples

Content type
application/json

Statistics for Acme Corporation's invoice processing workflow.

{
  • "workflow_id": "wf-12345",
  • "total_runs": 150,
  • "completed": 145,
  • "failed": 5,
  • "avg_duration_ms": 200,
  • "p99_duration_ms": 350
}

Resume paused workflow for active processing

This endpoint is the key to unlocking potential in workflows that have hit a pause. Imagine the gears of a complex machine grinding to a halt awaiting approval—this endpoint breathes life back into them. By resuming paused nodes within a workflow's DAG, it ensures that no opportunity for progress is lost.

Responses

Response samples

Content type
application/json
null

Retrieve organization-specific workflow details

Explore the dynamic landscape of your organization's workflows with this endpoint. It offers a window into the lifecycle, scope, and status of active workflows, empowering you to oversee and optimize your processes with precision.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 2,
  • "hasMore": true,
  • "cursorField": "updated_at"
}

Initiate workflow intent creation

Embark on the journey of crafting a new workflow intent, a crucial step in automating human-AI collaboration. This endpoint enables you to define the blueprint for a workflow, setting the stage for seamless orchestration and task execution.

Request Body schema: application/json
required
name
required
string

The name of the workflow intent

description
string

A detailed description of what the workflow intends to achieve

capabilityGraph
required
Array of strings

Responses

Request samples

Content type
application/json

An example of creating a workflow intent for processing invoices in the 'acme' organization.

{
  • "name": "Invoice Processing",
  • "description": "Handles the processing of invoices submitted by vendors.",
  • "capabilityGraph": [
    ]
}

Response samples

Content type
application/json
null

Retrieve a specific workflow by ID

Discover the intricate details of a workflow by retrieving it using its unique identifier. This endpoint is a gateway to understanding how your organization's workflows are orchestrated, ensuring seamless task execution.

Responses

Response samples

Content type
application/json

An example showing successful retrieval of a workflow

{
  • "id": "wf1234",
  • "name": "Invoice Processing",
  • "status": "active",
  • "created_at": "2023-09-15T12:34:56Z",
  • "updated_at": "2023-10-01T08:45:23Z"
}

Update an existing workflow definition

In the world of dynamic task orchestration, workflows are the heart of managing complex processes. This endpoint empowers organizations to update these workflows, ensuring they adapt to evolving business requirements while maintaining the integrity of their lifecycle states.

Request Body schema: application/json
required
name
required
string

Human-readable name for the workflow

manifest
object

JSON object representing the workflow's structure and logic

lifecycle_state
string
Enum: "draft" "active" "archived"

Current state of the workflow in its lifecycle

builder_flags
object

Additional flags for workflow builder settings

Responses

Request samples

Content type
application/json

This example demonstrates updating the name and state of a workflow

{
  • "name": "Invoice Processing Workflow",
  • "lifecycle_state": "active",
  • "manifest": {
    },
  • "builder_flags": {
    }
}

Response samples

Content type
application/json
{
  • "id": "wf-12345",
  • "name": "Invoice Processing Workflow",
  • "manifest": {
    },
  • "lifecycle_state": "active",
  • "builder_flags": {
    }
}

Activate a Builder Workflow

Transform your workflow from a dormant state into action by activating it. This endpoint exists to empower organizations to seamlessly transition workflows into an active state, ensuring tasks are ready to be processed. Whether you're launching a new project or reviving an existing one, activating workflows is a critical step in the orchestration process.

Request Body schema: application/json
required
note
string

A note providing context or rationale for activating the workflow

Responses

Request samples

Content type
application/json

Activating a workflow with a note to explain the reason

{
  • "note": "Activating for Q4 invoice processing cycle"
}

Response samples

Content type
application/json
null

Duplicate an existing workflow

This endpoint allows you to create a new copy of an existing workflow within your organization, enabling iterative development and experimentation. By duplicating workflows, you can preserve original configurations while exploring new ideas, enhancing collaboration and innovation.

Request Body schema: application/json
required
name_suffix
string

Suffix to append to the original workflow name

Responses

Request samples

Content type
application/json

Duplicates a workflow with a custom suffix appended to the name

{
  • "name_suffix": " - new iteration"
}

Response samples

Content type
application/json

Response after successfully duplicating a workflow

{
  • "id": "workflow-1234",
  • "name": "Invoice Processing - new iteration",
  • "owner_did": "did:human:123456789abcdef",
  • "scope": "accounting",
  • "lifecycle_state": "draft"
}

Publish a workflow for organization

This endpoint breathes life into a workflow by publishing it within the HUMAN platform. It ensures readiness, transitions the workflow state, and opens the door to new possibilities for organizational or personal use.

Request Body schema: application/json
required
scope
required
string
Enum: "personal" "workspace" "org"

Defines the level at which the workflow will be visible upon publishing.

Responses

Request samples

Content type
application/json

Publishing a workflow to make it available across the workspace.

{
  • "scope": "workspace"
}

Response samples

Content type
application/json
{
  • "workflow": {
    },
  • "warnings": [ ],
  • "marketplace_note": null
}

Retrieve Workflow Run History

Unlock the past of your automation endeavors with this endpoint, allowing organizations to delve into the historical runs of specified workflows. By tracking these runs, you can learn from past outcomes, ensuring continuous improvement and refined orchestration strategies.

Responses

Response samples

Content type
application/json

An example of a successful response listing workflow runs.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "started_at",
  • "hasMore": false
}

Retrieve Workflow Analytics by ID

Delve into the analytics of your workflows with precision and clarity. This endpoint reveals insightful metrics, allowing organizations to optimize Human-AI orchestration. Discover performance trends and identify areas for improvement to enhance operational efficacy.

Responses

Response samples

Content type
application/json

Analytics for Acme Corp's invoice processing workflow showing success rates and improvement suggestions.

{
  • "run_counts": {
    },
  • "success_rate": 0.8,
  • "fallback_rate": 0.1,
  • "approval_frequency": 0.05,
  • "escalation_rate": 0.05,
  • "workforce_handoff_rate": 0.2,
  • "avg_completion_ms": 1500,
  • "connector_failure_rate": 0.02,
  • "step_failure_breakdown": {
    },
  • "improvement_suggestions": [
    ]
}

Retrieve workflow migration status

Delve into the lifecycle of your workflow as it transitions through updates. This endpoint provides insights into the current migration status, ensuring that your operations remain seamless and informed.

Responses

Response samples

Content type
application/json

An example showing a completed migration status for a workflow.

{
  • "status": "completed",
  • "details": "The workflow migration completed successfully without any issues."
}

Upgrade Workflow Step to Capability

Elevate your workflow step by enhancing its capabilities. This endpoint allows an organization to upgrade a specific step in a workflow, ensuring it meets new requirements and capabilities essential for advanced processing. By harnessing the power of the Capability Graph, organizations can track and adapt skill requirements dynamically.

Request Body schema: application/json
required
required_capabilities
required
Array of strings
required_connectors
Array of strings

Responses

Request samples

Content type
application/json

Upgrade the workflow step to include 'capability://ai.ocr' and 'capability://data.validation'.

{
  • "required_capabilities": [
    ],
  • "required_connectors": [
    ]
}

Response samples

Content type
application/json
{
  • "workflow": {
    },
  • "rung_before": 2,
  • "rung_after": 3
}

Events

Fetch organizational event logs

Delve into the chronicles of your organization with this endpoint, designed to retrieve a curated list of events. Whether you're tracking the past or steering towards your future, understanding your events is crucial for strategic decision-making.

Responses

Response samples

Content type
application/json

Retrieve the latest 10 events for Acme Corp, revealing recent interactions and changes.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursor": "2023-10-03T14:48:00.000Z",
  • "hasMore": false
}

Emit and log an event in the system

This endpoint allows the orchestration of human and AI interactions by emitting events that are securely logged and tracked. It ensures the integrity and provenance of actions within the HUMAN protocol by leveraging cryptographic proofs and distributed ledger technology. This guarantees transparency and trust in the interactions processed by the platform.

Request Body schema: application/json
required
event_type
required
string

The type of event being emitted. This is a required field.

payload
object

Arbitrary JSON object containing details relevant to the event.

subject
string

The subject related to this event, often a DID or other identifier.

emitter_agent_did
string

The DID of the agent emitting the event; if provided, the event will be signed.

Responses

Request samples

Content type
application/json

An event indicating an invoice has been processed by an agent within the 'acme' organization.

{
  • "event_type": "invoice.processed",
  • "payload": {
    },
  • "subject": "did:example:123456789",
  • "emitter_agent_did": "did:example:agent:acme"
}

Response samples

Content type
application/json
{
  • "event_id": "evt-5f6a3b4d2e7c",
  • "content_hash": "abc123def456",
  • "signed": true,
  • "created_at": "2023-10-01T12:34:56Z"
}

Stream Provenance Events via SSE

Dive into the heartbeat of your organization with a real-time stream of provenance events. This endpoint exists to ensure transparency and traceability, allowing you to monitor the flow of data and actions within your systems as they happen. Embrace the power of live data and make informed decisions with every beat.

Responses

Response samples

Content type
application/json

A continuous stream of events for an organization monitoring data provenance.

"event: event\ndata: {\"event_id\": \"evt-1234\", \"event_type\": \"data_update\", \"created_at\": \"2023-10-01T12:00:00Z\", \"org_did\": \"did:example:acme-org\"}\n\n"

Retrieve detailed event information

This endpoint unlocks the story behind an event by fetching its comprehensive details using its unique identifier. It's designed to ensure that organizations can trace back any event within their operations, maintaining a seamless record of activities with accountability and transparency.

Responses

Response samples

Content type
application/json

An event detailing the processing of an invoice by Acme Corporation.

{
  • "eventId": "evt-12345",
  • "orgDid": "did:example:acme123",
  • "timestamp": "2023-10-05T14:48:00.000Z",
  • "details": "Invoice INV-001 processed successfully."
}

Stream Duplex Session Events via SSE

Experience the continuous flow of events from a duplex session, leveraging Server-Sent Events (SSE) to keep you updated in real-time. This endpoint ensures you are at the forefront of session activity, providing insights and state changes as they happen.

Responses

Response samples

Content type
application/json
Example

Streaming active events from a live session.

"data: {\"type\":\"interaction\",\"detail\":\"user joined\",\"sessionId\":\"session123\",\"timestamp\":\"2023-10-12T07:20:50.52Z\"}\n\n"

Stream workforce events for an organization

Connect to a real-time stream of workforce events tailored for your organizational role. Designed to keep human agents and AI systems synchronized, this endpoint ensures you never miss an important update in your operational sphere.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve Inbound Companion Events

Dive into the world of asynchronous task orchestration with this endpoint, designed to unearth completed inbound events from the HUMAN platform. This endpoint is vital for organizations using the HUMAN protocol to seamlessly integrate and track event triggers orchestrated by AI, ensuring that no completed task goes unnoticed.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Ledger

Query Provenance Records with Filters

Uncover the history behind your data by querying provenance records with precision. This endpoint empowers you to trace the lineage of actions within your organization, filtering by specific actors, events, or timeframes. Dive deep into the Distributed Ledger to ensure transparency and accountability.

Request Body schema: application/json
required
object
query
string

Optional query string for advanced search

Responses

Request samples

Content type
application/json

Query provenance records for a specific organization and actor

{
  • "filters": {
    },
  • "query": "status:completed"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Retrieve Merkle proof for event verification

Unlock the cryptographic assurance of your event's integrity with a Merkle proof. This endpoint provides the cryptographic evidence necessary to independently verify an event's presence in the ledger, championing transparency and decentralization by eliminating reliance on HUMΛN's internal databases.

Responses

Response samples

Content type
application/json

A successful retrieval of the Merkle proof for a specific event.

{
  • "event_id": "event_123456",
  • "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  • "ledger_anchor_ref": "anchor_78910",
  • "proof": {
    }
}

Retrieve Passport's Latest Ledger Anchor

Unlock the cryptographic trail of your identity with this endpoint, offering a peek into the most recent ledger anchor of a Human Passport. This ensures trust and transparency as you explore the digital provenance of skills and tasks.

Responses

Response samples

Content type
application/json
{
  • "did": "did:human:123456789abcdefghi",
  • "anchor_id": "anchor123",
  • "batch_id": "batch456",
  • "merkle_root": "abcd1234efgh5678ijkl9101mnopqrst",
  • "merkle_proof": [
    ],
  • "leaf_index": 1,
  • "leaf_hash": "mnop1234qrst5678",
  • "transaction_hash": "tx1234567890abcdef",
  • "block_number": 123456,
  • "chain_id": 42,
  • "chain_name": "Ethereum Mainnet",
  • "anchored_at": "2023-10-01T12:00:00Z"
}

Attestation

Attest Provenance Event for Verification

In the intricate dance of information and identity, this endpoint allows trusted parties to attest to the authenticity of a provenance event. By doing so, it ensures the integrity and trustworthiness of the data within the HUMAN ecosystem, binding the present to the verified past.

Request Body schema: application/json
required
org_did
string

Decentralized identifier for the organization.

provenance_record_id
required
string

Unique identifier for the provenance record.

object

Optional payload to include additional metadata for attestation.

Responses

Request samples

Content type
application/json

Attest a provenance record for the 'acme' organization.

{
  • "org_did": "did:human:acme123",
  • "provenance_record_id": "prov-456def789",
  • "attestation_payload": {
    }
}

Response samples

Content type
application/json
null

Create license attestation for a Passport

This endpoint allows organizations to attest a license to a subject's Passport, strengthening trust in identity verification within the HUMAN ecosystem. By enabling license attestations, organizations can securely affirm the skills and credentials of individuals, enhancing the reliability of the Capability Graph.

Request Body schema: application/json
required
subject_did
required
string

The decentralized identifier (DID) of the subject to whom the license is being attested

required
object

Additional metadata describing the license

Responses

Request samples

Content type
application/json

Attesting a driver's license for a subject.

{
  • "subject_did": "did:human:123456789abcdefghi",
  • "license_details": {
    }
}

Response samples

Content type
application/json
null

Retrieve passport's attestations

Unearth the verified skills and credentials linked to a passport within the HUMAN platform. This endpoint empowers users to view the attestations tied to a cryptographic identity, revealing the journey and trustworthiness of the passport holder.

Responses

Response samples

Content type
application/json

Retrieve a list of active attestations for a specific passport, demonstrating the credentials issued by various entities.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Connectors

Create and register a new connector

In the vast landscape of digital ecosystems, connectors serve as bridges, enabling seamless interactions between diverse platforms. This endpoint allows you to register a new connector, giving it a digital handshake to the HUMAN protocol, ensuring it can perform its duties in harmony with others.

Request Body schema: application/json
required
required
object
publisher_id
string
visibility
string
Enum: "org_private" "public"
certified
boolean
org_id
string
pricing_model
string
Enum: "free" "paid"
config
object

Responses

Request samples

Content type
application/json

Registering Acme's invoice processing connector for public visibility.

{
  • "manifest": {
    },
  • "publisher_id": "acme-publisher-id",
  • "visibility": "public",
  • "certified": true,
  • "org_id": "org-12345",
  • "pricing_model": "free",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "connector-67890",
  • "connector_id": "acme-invoice-connector",
  • "name": "Acme Invoice Processor",
  • "provider": "Acme Corp",
  • "version": "1.0.0",
  • "status": "active"
}

Retrieve connector details by identifier

Delve into the world of connectors with this endpoint, which unveils the secrets of a connector's metadata using its unique identifier. Whether you're orchestrating tasks or verifying integrations, this endpoint ensures you have the detailed insights needed to manage and optimize your connectors effectively.

Responses

Response samples

Content type
application/json

Retrieve the metadata for Acme's invoice processing connector.

{
  • "id": "connector-123",
  • "connector_id": "invoice-processor",
  • "name": "Acme Invoice Processor",
  • "provider": "Acme Inc.",
  • "version": "1.2.3",
  • "description": "Processes invoices for Acme's internal systems.",
  • "icon_url": "https://example.com/icons/acme-invoice.png",
  • "capabilities": [
    ],
  • "required_scopes": [
    ],
  • "oauth_config": {
    },
  • "deployment": {
    },
  • "publisher_id": "pub-456",
  • "visibility": "public",
  • "certified": true,
  • "pricing_model": "pay-as-you-go"
}

Discover and explore marketplace connectors

Dive into the vibrant ecosystem of HUMAN's marketplace where you can explore and filter public connectors. This endpoint empowers you to search by various parameters, discovering connectors that meet your specific needs and capabilities. It's designed to enhance your interaction with the HUMAN ecosystem by providing a curated list of AI tools and connectors.

Responses

Response samples

Content type
application/json

An example response showing a list of connectors from the marketplace, filtering by provider 'acme'.

{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "2"
}

Retrieve the organization's connector installations

Explore the landscape of connectors your organization has entrusted to carry out crucial tasks. This endpoint unveils the tapestry of installations, helping you manage and optimize the technological prowess at your disposal.

Responses

Response samples

Content type
application/json

Retrieve a list of active connectors installed by the 'acme' organization.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Retrieve detailed connector information

Dive into the rich details of any public connector available on the HUMAN marketplace. This endpoint allows you to explore the capabilities and statistics of connectors, empowering informed decisions about integration and usage.

Responses

Response samples

Content type
application/json
{
  • "connector_id": "b7d2e9f1",
  • "name": "Invoice Processor",
  • "provider": "Acme Corp",
  • "description": "Automates invoice processing tasks",
  • "long_description": "The Invoice Processor streamlines the handling of invoices by leveraging AI to ensure accuracy and speed.",
  • "icon_url": "https://example.com/icons/invoice-processor.png",
  • "version": "1.4.2",
  • "publisher": {
    },
  • "certified": true,
  • "pricing_model": "subscription",
  • "capabilities": [
    ],
  • "oauth": {},
  • "deployment_modes": [
    ],
  • "configuration_schema": {
    },
  • "health_status": "healthy",
  • "last_health_check_at": "2023-10-01T12:00:00Z",
  • "statistics": {
    },
  • "created_at": "2022-06-15T08:30:00Z",
  • "updated_at": "2023-09-10T14:45:00Z"
}

Install a Connector for Organization

In the HUMAN ecosystem, connectors are bridges that allow organizations to integrate external services seamlessly. This endpoint empowers your organization to install a connector, ensuring a smooth flow of operations across platforms. The installation process is authenticated via a Passport delegation token, safeguarding your organization's integrity.

Request Body schema: application/json
required
deployment_mode
required
string
Enum: "cloud" "hybrid" "self-hosted"

The mode in which the connector will be deployed.

granted_permissions
required
Array of strings

A list of permissions the connector is granted upon installation.

object

Optional configuration settings specific to the connector.

Responses

Request samples

Content type
application/json

This example demonstrates installing a connector with cloud deployment mode and specific permissions.

{
  • "deployment_mode": "cloud",
  • "granted_permissions": [
    ],
  • "config": {}
}

Response samples

Content type
application/json
Example

An example response when a connector is installed and active.

{
  • "installation_id": "install_123456",
  • "connector_id": "connector_7890",
  • "status": "active",
  • "installed_at": "2023-10-15T12:00:00Z"
}

Uninstall a marketplace connector

This endpoint allows you to seamlessly remove a connector from your organization's ecosystem, ensuring that only relevant tools remain active. By managing your connectors effectively, you maintain a streamlined and secure operational environment, fostering both innovation and governance.

Request Body schema: application/json
required
entity_id
string

The unique identifier of the entity within the organization.

Responses

Request samples

Content type
application/json

Uninstalls a connector for the 'acme' organization.

{
  • "entity_id": "acme-organization-123"
}

Response samples

Content type
application/json
null

Publish a connector to the marketplace

In the HUMAN ecosystem, publishing a connector is more than just uploading code—it's about establishing a trusted identity and sharing innovations with the world. This endpoint allows verified developers to publish their connectors, ensuring that their creations carry their identity and reputation across the HUMAN network. With a focus on integrity and security, published connectors must meet identity verification standards, ensuring that every contribution is backed by a real person.

Request Body schema: application/json
required
connector_id
string

Unique identifier for the connector

name
required
string

Human-readable name of the connector

description
string

Detailed description of the connector's functionality

version
required
string

Semantic version of the connector

object

Connector manifest details

handles_sensitive_data
boolean

Indicates if the connector handles sensitive data

pricing_model
string
Enum: "free" "paid" "freemium"

The pricing model for the connector

deployment_modes
Array of strings
Items Enum: "cloud" "hybrid" "self-hosted"

Supported deployment modes

Responses

Request samples

Content type
application/json

Publishing a simple connector with a free pricing model and cloud deployment.

{
  • "name": "acme-invoice-processor",
  • "version": "1.0.0",
  • "description": "Processes invoices for the Acme organization",
  • "manifest": {
    },
  • "pricing_model": "free",
  • "deployment_modes": [
    ]
}

Response samples

Content type
application/json
{
  • "publish_id": "pub-123456",
  • "status": "published",
  • "publisher_did": "did:human:1234abcd",
  • "connector_id": "acme-invoice-processor",
  • "name": "Acme Invoice Processor",
  • "version": "1.0.0",
  • "message": "You're verified. Your published work carries your identity — it's your reputation, portable and permanent.",
  • "created_at": "2023-10-12T07:20:50.52Z"
}

Submit a rating for a marketplace connector

In the vibrant ecosystem of HUMAN's marketplace, connectors are the lifeblood that enable seamless integration. This endpoint empowers users to express their satisfaction or critique by rating connectors they have installed. A rating not only influences the connector's reputation but also guides future users in their decision-making process.

Request Body schema: application/json
required
rating
required
integer [ 1 .. 5 ]

The rating score given to the connector, must be between 1 and 5.

installation_id
required
string

The unique identifier of the connector installation being rated.

review_text
string

An optional textual review providing more context about the rating.

Responses

Request samples

Content type
application/json

A rating example where Acme Corp rates a connector they use for invoice processing.

{
  • "rating": 4,
  • "installation_id": "inst_12345",
  • "review_text": "The connector works well but could use more features."
}

Response samples

Content type
application/json
{
  • "rating_id": "rat_67890",
  • "connector_id": "con_54321",
  • "rating": 4,
  • "review_text": "The connector works well but could use more features.",
  • "updated_at": "2023-10-05T14:48:00.000Z"
}

Retrieve ratings for a specific connector

Explore the diverse perspectives of users by accessing ratings for any given connector on the HUMAN marketplace. This endpoint offers a glimpse into the community's feedback, essential for refining and optimizing AI-human collaboration tools. Dive into the data to understand the connector's performance and user satisfaction, while contributing to an open ecosystem of trust and innovation.

Responses

Response samples

Content type
application/json

Ratings for connector showing user feedback and summary statistics.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "summary": {
    }
}

Update Connector Installation Details

This endpoint allows organizations to update the configuration or status of a specific connector installation. By enabling such updates, organizations can ensure their integrations remain effective and responsive to changing business needs.

Request Body schema: application/json
required
status
string
Enum: "active" "suspended"

The desired status for the installation.

config
object

The configuration settings for the installation.

Responses

Request samples

Content type
application/json
Example

This example demonstrates updating an installation's status to 'active'.

{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "installation_id": "install-12345",
  • "status": "active",
  • "config": {},
  • "updated_at": "2023-10-01T14:48:00.000Z"
}

Retrieve Installation Usage Statistics

Uncover the journey of your connector's performance over the last 30 days. This endpoint provides an insightful peek into the success, challenges, and costs associated with your installations, ensuring you have the information needed to optimize your operations.

Responses

Response samples

Content type
application/json
null

Store connector credentials securely

This endpoint empowers organizations by securely storing credentials for connectors, ensuring proper authentication and authorization. It is crucial for maintaining seamless integration and automated workflows across varied systems, embodying the dynamic nature of modern orchestration.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve Decrypted Connector Credentials

Unlock the power of seamless integration by retrieving decrypted credentials for a specified connector. This endpoint ensures that entities can securely access credentials, enabling the orchestration of tasks without compromising security. By tailoring retrieval to specific scopes, it maximizes flexibility while maintaining stringent control over sensitive data.

Responses

Response samples

Content type
application/json

A successful response showing decrypted credentials for the 'acme' organization connector.

{
  • "credential": {
    },
  • "decrypted_credentials": {
    }
}

Retrieve Credential List for Connector

Unearth the hidden troves of credentials tied to a specific connector, a crucial step in managing your entity's digital keys. This endpoint allows the secure listing of credentials, providing transparency and control over who can access and perform operations within your system.

Responses

Response samples

Content type
application/json

An example of credentials retrieved for a specific connector.

{
  • "credentials": [
    ],
  • "count": 1
}

Securely update connector webhook secret

In the ever-evolving world of digital interactions, ensuring secure communication is paramount. This endpoint allows organizations to update the signing secret for their connectors, reinforcing the security of webhook communications. It exists to ensure that data integrity and authenticity are maintained through cryptographic measures, allowing organizations to confidently interact with HUMAN's powerful orchestration capabilities.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve connector's webhook secret metadata

Unlock the orchestration potential of AI-human collaboration by fetching essential webhook secret metadata for a connector. This endpoint ensures secure and reliable communication between your services, safeguarding data integrity and authenticity.

Responses

Response samples

Content type
application/json
null

Deactivate a Connector's Webhook Secret

In a world where data flows seamlessly, connectors play a crucial role in linking systems. This endpoint allows organizations to deactivate the webhook secret for a specific connector, enhancing security by disabling outdated or compromised integrations. By doing so, it ensures that the data shared through these connectors remains secure and controlled.

Responses

Response samples

Content type
application/json

Successfully deactivating the webhook secret for connector ID 1234

{
  • "connector_id": "1234",
  • "active": false,
  • "deactivated_at": "2023-12-01T12:34:56Z"
}

Upgrade a connector to a new version

In the ever-evolving landscape of digital tools, keeping your connectors up-to-date is paramount for leveraging new features and maintaining security. This endpoint allows organizations to seamlessly upgrade their connectors to newer versions, ensuring they are always operating with the latest capabilities.

Request Body schema: application/json
required
version
required
string

The semantic version number to upgrade the connector to, e.g., '1.1.0'.

force
boolean

Flag to force the upgrade even if it is a downgrade.

Responses

Request samples

Content type
application/json

Example showing how to upgrade a connector to version 2.0.0

{
  • "version": "2.0.0",
  • "force": false
}

Response samples

Content type
application/json
{
  • "installation_id": "inst-12345",
  • "connector_id": "conn-67890",
  • "version_installed": "2.0.0"
}

Retrieve list of marketplace connectors

Explore the vast ecosystem of connectors available on the HUMAN Marketplace. This endpoint provides a curated list of connectors, enabling seamless integration and enhancing the capability graph of your organization. Whether you're looking to expand your toolkit or ensure compatibility, this list is your gateway to innovation.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieve organization connector credentials

Dive into the heart of connectivity! This endpoint fetches a curated list of connector credentials tied to your organization. Designed for seamless integration, it ensures that your connectors are up-to-date and ready to handle your organization's demands, showcasing their status and health.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Initiate OAuth Flow for Connector

This endpoint empowers organizations to seamlessly start an OAuth authentication process for a specified connector, ensuring secure connectivity and identity delegation. It exists to facilitate secure integrations while maintaining human oversight in AI orchestration.

Request Body schema: application/json
required
return_url
string

URL to redirect after authorization

Responses

Request samples

Content type
application/json

Starts the OAuth process and specifies where to redirect upon completion.

{}

Response samples

Content type
application/json

The OAuth process is started, providing URLs for user redirection.

{}

Test connectivity for a specific connector

In the ever-evolving landscape of Human-AI orchestration, ensuring smooth communication channels is key. This endpoint lets you verify the live connectivity of a specified connector, using a quick probe, to ensure seamless task routing and skill tracking within the HUMAN ecosystem.

Request Body schema: application/json
required
probe
string

A test string sent to the connector to evaluate its responsiveness.

Responses

Request samples

Content type
application/json

Sending a simple probe to test connectivity.

{
  • "probe": "ping"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "connector_id": "acme123",
  • "latency_ms": 15
}

Disconnect a connector for an organization

In the HUMAN ecosystem, managing your connector's lifecycle is crucial for maintaining operational integrity. This endpoint allows organizations to disconnect a specific connector, ensuring security by revoking access and updating the connector's status. It's a vital tool for organizations aiming to maintain a secure and up-to-date environment.

Request Body schema: application/json
required
revoke_tokens
boolean

Indicate if tokens should be revoked during the disconnect process

Responses

Request samples

Content type
application/json

Demonstrates disconnecting a connector and revoking its tokens

{
  • "revoke_tokens": true
}

Response samples

Content type
application/json
{
  • "disconnected": true
}

Registration

Create and register a new connector

In the vast landscape of digital ecosystems, connectors serve as bridges, enabling seamless interactions between diverse platforms. This endpoint allows you to register a new connector, giving it a digital handshake to the HUMAN protocol, ensuring it can perform its duties in harmony with others.

Request Body schema: application/json
required
required
object
publisher_id
string
visibility
string
Enum: "org_private" "public"
certified
boolean
org_id
string
pricing_model
string
Enum: "free" "paid"
config
object

Responses

Request samples

Content type
application/json

Registering Acme's invoice processing connector for public visibility.

{
  • "manifest": {
    },
  • "publisher_id": "acme-publisher-id",
  • "visibility": "public",
  • "certified": true,
  • "org_id": "org-12345",
  • "pricing_model": "free",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "connector-67890",
  • "connector_id": "acme-invoice-connector",
  • "name": "Acme Invoice Processor",
  • "provider": "Acme Corp",
  • "version": "1.0.0",
  • "status": "active"
}

Register a new resource schema

In the dynamic realm of digital resources, schemas are the blueprints that guide interaction. This endpoint empowers organizations to register new schema versions, ensuring consistent understanding and validation across distributed systems. By enforcing authority rules, it safeguards namespace integrity, aligning with HUMAN's commitment to secure and trustworthy orchestration.

Request Body schema: application/json
required
kind
required
string

The resource kind identifier (e.g., core.email.message).

definition
required
object

A JSON Schema (draft 2020-12) detailing the structure of the resource kind.

authority_did
required
string

The Decentralized Identifier (DID) claiming authority over this kind's namespace.

created_by
required
string

DID of the entity (human or CI) registering the schema.

Responses

Request samples

Content type
application/json

Shows registration of a schema for email messages within the core namespace.

{
  • "kind": "core.email.message",
  • "definition": {
    },
  • "authority_did": "did:org:human",
  • "created_by": "did:agent:regina-phalange"
}

Response samples

Content type
application/json
{
  • "kind": "core.email.message",
  • "registered_at": "2023-10-01T12:00:00Z"
}

Register a Human Passport for Discovery

Embark on the journey of identity verification by registering your cryptographic Passport with HUMAN. This endpoint ensures the integrity of the self-signed proof from your device-rooted Passport, making it discoverable within the HUMAN ecosystem.

Request Body schema: application/json
required
passportData
required
string

Base64-encoded passport data containing the cryptographic proof.

Responses

Request samples

Content type
application/json

Registering a new passport for the Acme organization.

{
  • "passportData": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
{
  • "message": "Passport registered successfully.",
  • "passportId": "acme-passport-12345"
}

Register a new agent under an organization

Embark on a journey with HUMAN by registering a new agent. This process not only formalizes an agent's identity but also seamlessly integrates them into the HUMAN ecosystem, ensuring their skills are tracked and tasks are routed efficiently.

Request Body schema: application/json
required
One of
agent_id
required
string

A unique identifier for the agent.

agent_external_id
string

An external identifier for the agent, used if agent_id is not provided.

object

Additional metadata for the agent registration.

Responses

Request samples

Content type
application/json
Example

An example showing registration with a specified agent_id.

{
  • "agent_id": "agent_12345",
  • "metadata": {
    }
}

Response samples

Content type
application/json

A response example of a successfully registered agent.

{
  • "registration_id": "hos_ag_abcdef123456",
  • "agent_id": "agent_12345",
  • "registered_at": "2023-10-01T12:34:56Z"
}

Metadata

Retrieve connector details by identifier

Delve into the world of connectors with this endpoint, which unveils the secrets of a connector's metadata using its unique identifier. Whether you're orchestrating tasks or verifying integrations, this endpoint ensures you have the detailed insights needed to manage and optimize your connectors effectively.

Responses

Response samples

Content type
application/json

Retrieve the metadata for Acme's invoice processing connector.

{
  • "id": "connector-123",
  • "connector_id": "invoice-processor",
  • "name": "Acme Invoice Processor",
  • "provider": "Acme Inc.",
  • "version": "1.2.3",
  • "description": "Processes invoices for Acme's internal systems.",
  • "icon_url": "https://example.com/icons/acme-invoice.png",
  • "capabilities": [
    ],
  • "required_scopes": [
    ],
  • "oauth_config": {
    },
  • "deployment": {
    },
  • "publisher_id": "pub-456",
  • "visibility": "public",
  • "certified": true,
  • "pricing_model": "pay-as-you-go"
}

Retrieve metadata for a secret key

Unlock the insights without the secrets. This endpoint provides metadata about a secret key, offering a glimpse into its lifecycle and attributes without revealing its value. It's a crucial tool for auditing and understanding the secrets you manage, ensuring your operations maintain transparency and control.

Responses

Response samples

Content type
application/json
Example
{
  • "key": "api-key-1234",
  • "description": "Production API key for payment processing",
  • "rotatable": true,
  • "expires_at": "2025-12-31T23:59:59.000Z",
  • "created_at": "2023-01-15T12:34:56.000Z",
  • "updated_at": "2023-06-10T08:22:44.000Z"
}

Retrieve vault document metadata

Explore the labyrinth of your digital vault by retrieving only the metadata of documents within a specified collection. This endpoint empowers you to efficiently navigate and manage your document collections without exposing sensitive details.

Responses

Response samples

Content type
application/json

An example response showing metadata for documents in a vault collection.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Agents

Retrieve a paginated list of agents

Discover the dynamic landscape of your organization's AI workforce. This endpoint not only lists agents but paints a picture of their capabilities, empowering you to manage and optimize your human-AI orchestration effectively. By leveraging cursor-based pagination, it ensures smooth navigation through extensive datasets.

Responses

Response samples

Content type
application/json

A seamless retrieval of agents for the 'acme' organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at",
  • "hasMore": false
}

Retrieve details of a specific agent

Discover the capabilities and identity of a specific agent within the HUMAN ecosystem. This endpoint allows you to access detailed information about an agent, tracked through the HUMAN Passport and Capability Graph, to understand its roles and functions. Uncover how agents are orchestrated to perform tasks safely and transparently.

Request Body schema: application/json
required
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
null

Retrieve Agent by Decentralized ID

Discover the unique capabilities and skills of a specific agent, identified by their cryptographic Passport. This endpoint is your gateway to understanding the role and history of an agent within the HUMAN ecosystem, offering insights into their past tasks and skillset.

Responses

Response samples

Content type
application/json

Details of an agent from ACME Corp known for processing complex invoices.

{
  • "agentDid": "did:human:123456789abcdefghi",
  • "name": "Invoice Processor 3000",
  • "capabilities": [
    ],
  • "lastActive": "2023-10-15T14:48:00Z"
}

Retrieve recent decision events for an agent

Uncover the trail of decisions governed by HUMAN's sophisticated orchestration, as this endpoint unveils recent decision events associated with a specific agent. Whether you're monitoring task progress or conducting audits, these events offer a window into the agent's operational history, ensuring transparency and accountability.

Responses

Response samples

Content type
application/json
null

Retrieve Agent Artifacts with Provenance

Uncover the wealth of artifacts associated with a specific agent within an organization, tracing the lineage and evolution of each piece. This endpoint helps ensure transparency and trust in AI-driven tasks by presenting a detailed history of artifact creation and modification.

Responses

Response samples

Content type
application/json
{
  • "agent_id": "agent-1234",
  • "org_did": "did:human:acme",
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Deploy an agent with identity minting

Embark on the journey of deploying an agent where identity and capability converge. This endpoint mints a Passport for your agent, anchoring its identity in the distributed ledger and equipping it with the skills needed for its mission. It's not just deployment; it's the birth of a digital entity.

Request Body schema: application/json
required
required
object
profile
string
Default: "hosted"

Responses

Request samples

Content type
application/json

Deploys an agent named 'invoice-processor' for the 'acme' organization with AI capabilities.

{
  • "manifest": {
    }
}

Response samples

Content type
application/json
null

Retrieve detailed agent information by ID

Unlock the power of your HUMAN agents by retrieving detailed information using their unique identifiers. Whether you're exploring agents by their cryptographic DIDs or their organizational identifiers, this endpoint provides a comprehensive view of an agent's identity, capabilities, and operational context.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Resume a paused agent's operations

In the dynamic world of Human-AI collaboration, agents sometimes need to pause. This endpoint breathes life back into a paused agent, restoring its active status and enabling it to perform its designated tasks. It's a critical function for maintaining seamless operations and ensuring that your digital workforce is always at the ready.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Permanently retire a specified agent

In the dynamic world of human and AI collaboration, sometimes an agent's journey must conclude. This endpoint allows you to retire an agent, ensuring that it can no longer participate in the orchestration process. By doing so, organizations maintain a clean and up-to-date roster of active agents, preserving the integrity and reliability of the HUMAN platform.

Request Body schema: application/json
required
reason
string

Optional explanation for retiring the agent.

Responses

Request samples

Content type
application/json

Retiring an agent with a specific reason provided.

{
  • "reason": "Project completed, agent services no longer required"
}

Response samples

Content type
application/json

Example response after successfully retiring an agent.

{
  • "agent": {
    }
}

Retrieve agent execution history

Delve into the rich tapestry of an agent's past activities by retrieving its execution history. This endpoint allows you to explore how agents have been invoked, their performance over time, and any associated costs or errors, providing transparency and accountability.

Responses

Response samples

Content type
application/json

A list of past executions for agent 'acme:invoice-processor'.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "execution_id"
}

Retrieve all deployed agent versions

Explore the evolution of your AI agents with this endpoint, which lists all the deployed versions. This helps organizations track changes over time, ensuring the right skills are deployed at the right moments, ultimately enhancing AI strategy and effectiveness.

Responses

Response samples

Content type
application/json

List of versions for the agent 'acme:123'.

{
  • "data": [
    ],
  • "pagination": {
    }
}

Stream real-time logs for agents

Dive into the pulsating life of an agent with real-time log streaming. Though this feature is a placeholder for now, it promises to reveal the intricate dance of actions and reactions in your AI operations once fully implemented. Keep your eyes peeled for Phase 6e when this becomes a reality.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/not-found",
  • "title": "Agent Not Found",
  • "status": 404,
  • "detail": "No agent found with DID or org_agent_id matching 'agent123'. Verify the agent ID and try again."
}

Register a new agent under an organization

Embark on a journey with HUMAN by registering a new agent. This process not only formalizes an agent's identity but also seamlessly integrates them into the HUMAN ecosystem, ensuring their skills are tracked and tasks are routed efficiently.

Request Body schema: application/json
required
One of
agent_id
required
string

A unique identifier for the agent.

agent_external_id
string

An external identifier for the agent, used if agent_id is not provided.

object

Additional metadata for the agent registration.

Responses

Request samples

Content type
application/json
Example

An example showing registration with a specified agent_id.

{
  • "agent_id": "agent_12345",
  • "metadata": {
    }
}

Response samples

Content type
application/json

A response example of a successfully registered agent.

{
  • "registration_id": "hos_ag_abcdef123456",
  • "agent_id": "agent_12345",
  • "registered_at": "2023-10-01T12:34:56Z"
}

Management

Retrieve a paginated list of agents

Discover the dynamic landscape of your organization's AI workforce. This endpoint not only lists agents but paints a picture of their capabilities, empowering you to manage and optimize your human-AI orchestration effectively. By leveraging cursor-based pagination, it ensures smooth navigation through extensive datasets.

Responses

Response samples

Content type
application/json

A seamless retrieval of agents for the 'acme' organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at",
  • "hasMore": false
}

Remove an installed extension securely

Uninstalling an extension is crucial when you no longer need its capabilities or when it's outdated. This endpoint ensures safe removal by verifying user permissions, maintaining system integrity through transactional deletions, and updating provenance records. Such careful measures protect your organization's data and AI processes.

Responses

Response samples

Content type
application/json

An extension is removed successfully from the system.

null

Deactivate a workflow by ID

In the dynamic world of task management, workflows often need to be paused or revisited. This endpoint allows you to deactivate a workflow, transitioning it to a 'draft' state. By doing so, teams can refine tasks without impacting the live environment, ensuring meticulous quality control before reactivation.

Request Body schema: application/json
required
note
string

An optional note providing context or reasoning for the deactivation.

Responses

Request samples

Content type
application/json

Deactivating a workflow with a note.

{
  • "note": "Pausing workflow for quarterly review."
}

Response samples

Content type
application/json
{
  • "id": "workflow-123",
  • "orgId": "acme-corp",
  • "name": "Invoice Processing",
  • "lifecycleState": "draft",
  • "updatedAt": "2023-10-05T14:48:00.000Z"
}

HumanOS

Invoke Agent via Capability or Workflow

The Unified Human-AI Orchestration Gateway empowers organizations to seamlessly orchestrate tasks across human and AI agents. By leveraging capability URIs, agent URIs, or workflow capability steps, users can route tasks dynamically and ensure AI safety through HumanOS. This endpoint is the backbone of intelligent task routing, ensuring tasks reach the most capable executor.

Request Body schema: application/json
required
One of
capability
required
string^capability://

Capability URI for task routing

async
boolean

Whether the invocation should be asynchronous

object

Input parameters for the agent

Responses

Request samples

Content type
application/json
Example

Example invoking an agent using a capability URI.

{
  • "capability": "capability://org123/email.read",
  • "async": false,
  • "input": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "routing": {
    },
  • "metadata": {
    },
  • "action_receipt": {
    }
}

Retrieve Async Execution Status

Uncover the current status and intricate details of an asynchronous execution task. This endpoint empowers users by providing not just the status, but a comprehensive view into the job's lifecycle and its journey through the HumanOS system. It's designed for those who need insights into task progress and execution outcomes in a distributed environment.

Responses

Response samples

Content type
application/json

Retrieve detailed status of an async execution for a task.

{
  • "id": "exec_12345",
  • "task_id": "task_67890",
  • "agent_id": "agent_alpha",
  • "requester_passport_id": "passport_abc123",
  • "job_id": "job_54321",
  • "queue_name": "mainQueue",
  • "priority": 5,
  • "status": "completed",
  • "result": {
    },
  • "error": null,
  • "progress_percent": 100,
  • "progress_message": "Execution completed successfully.",
  • "callback_url": "https://example.com/callback",
  • "callback_success": true,
  • "callback_attempts": 1,
  • "max_attempts": 3,
  • "current_attempt": 1,
  • "queued_at": "2023-10-21T10:20:30Z",
  • "started_at": "2023-10-21T10:30:00Z",
  • "completed_at": "2023-10-21T11:00:00Z",
  • "paused_at": null,
  • "paused_by": null,
  • "pause_reason": null,
  • "resume_count": 0,
  • "processing_pause_requested_at": null,
  • "provenance_id": "prov_334455",
  • "run_state": "finalized",
  • "current_step": "summary"
}

Retrieve effective HumanOS tuning actions

In a world where AI safety and human collaboration are paramount, understanding the effective tuning actions within your HumanOS ecosystem is crucial. This endpoint empowers organizations by offering insights into the most impactful tuning actions, ensuring your AI and human agents are aligned and performing at their best.

Responses

Response samples

Content type
application/json

A list of effective tuning actions for the organization 'acme'.

{
  • "org_did": "did:human:1234567890abcdef",
  • "scope": "user",
  • "effective": [
    ],
  • "actions_considered": 5
}

Compare Tuning to Default Settings

This endpoint unveils the hidden drift between your organization's custom HumanOS tuning and the established defaults. By examining this divergence, organizations can ensure their Human-AI orchestration aligns with desired operational standards, enhancing both efficiency and safety.

Responses

Response samples

Content type
application/json

Illustrates an organization comparing their current settings with default ones.

{
  • "org_did": "did:example:acme",
  • "scope": "user",
  • "effective": {
    },
  • "defaults": {
    },
  • "drift": {
    },
  • "actions_considered": 150
}

Create a new tuning action

This endpoint empowers organizations to tailor their HumanOS interactions by registering tuning actions like setting preferences or muting sources. It's a dynamic tool for enhancing AI safety and operational precision, ensuring that actions align with organizational policies and adaptive learning strategies.

Request Body schema: application/json
required
action_type
required
string
Enum: "revert_tuning" "set_digest_mode" "mute_source" "unmute_source" "set_preference"

The type of tuning action to execute

payload
required
object

Parameters specific to the action type

scope
string
Enum: "user" "org" "team"

The scope of the tuning action

approval_request_id
string

ID for the approval request if required

expires_at
string <date-time>

The expiration time of the tuning action

Responses

Request samples

Content type
application/json

Illustrates setting a user preference within allowed parameters

{
  • "action_type": "set_preference",
  • "payload": {
    },
  • "scope": "user",
  • "expires_at": "2023-12-31T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "action_id": "tun123456",
  • "org_did": "did:human:acme",
  • "action_type": "set_preference",
  • "scope": "user",
  • "payload": {
    },
  • "expires_at": "2023-12-31T23:59:59Z",
  • "created_at": "2023-10-15T12:00:00Z"
}

Submit new capture for HUMAN orchestration

Initiate a capture process on the HUMAN platform, enabling seamless orchestration between humans and AI. This endpoint is a pivotal entry point to submit diverse data types for further processing and task routing, ensuring data integrity and provenance within a decentralized system.

Request Body schema: application/json
required
source_kind
required
string
Enum: "text" "webhook" "audio" "video" "transcript"

Identifies the type of data source being captured.

submitter_ref
string

Reference to the entity submitting the capture.

scope
string

The scope within which the capture is being made, defaults to 'org'.

intent
string

The intended outcome or purpose of the capture.

payload_ref
string

Reference to the payload data, if applicable.

payload
object

The actual data being captured.

provenance_parent_id
string

ID of the parent capture, if this is a continuation or related capture.

effective_config_keys
object

Configuration keys influencing capture processing.

enqueue_invocation
boolean

Flag indicating whether an invocation should be enqueued.

enqueue_human_call
boolean

Flag indicating whether a human call task should be queued.

invocation_task_type
string

Specifies the type of task to invoke if enqueuing.

trace_id
string

Trace identifier for tracking invocation.

invocation_input
object

Input details for the invocation task.

Responses

Request samples

Content type
application/json

Submits a text-based capture for processing by HUMAN.

{
  • "source_kind": "text",
  • "submitter_ref": "did:human:acme-agent",
  • "scope": "org",
  • "intent": "transcription",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "capture_id": "cap_123456",
  • "org_did": "did:human:acme",
  • "source_kind": "text",
  • "submitted_at": "2023-10-01T12:00:00Z",
  • "submitter_ref": "did:human:acme-agent",
  • "scope": "org",
  • "payload_ref": "ref_987654",
  • "intent": "transcription",
  • "provenance_parent_id": null,
  • "effective_config_keys": { },
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-01T12:00:00Z",
  • "invocation_enqueued": true,
  • "async_execution_id": "exe_654321",
  • "capture_invocation_error": null
}

Retrieve HumanOS Task Captures

Unlock insights into task orchestration by fetching a list of captures associated with your organization's decentralized identity. This endpoint empowers organizations to track provenance and understand task flows through the HUMAN platform.

Responses

Response samples

Content type
application/json

An organization retrieves a paginated list of task captures for analysis.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Retrieve detailed capture information

Uncover the tapestry of HUMAN's orchestration by retrieving detailed information about a specific data capture. This endpoint empowers organizations to track and understand the provenance and intent of their AI and human interactions, enhancing transparency and accountability.

Responses

Response samples

Content type
application/json

Details of a capture from the 'acme' organization.

{
  • "capture_id": "12345",
  • "org_did": "did:example:acme",
  • "source_kind": "sensor",
  • "submitted_at": "2023-10-01T12:00:00Z",
  • "submitter_ref": "agent:john.doe",
  • "scope": "invoice-processing",
  • "payload_ref": "payload:98765",
  • "payload": {
    },
  • "intent": "Automated invoice processing",
  • "provenance_parent_id": "prov:67890",
  • "effective_config_keys": [
    ],
  • "created_at": "2023-09-30T10:00:00Z",
  • "updated_at": "2023-10-01T11:00:00Z"
}

Create a new HumanOS watch

The endpoint empowers organizations to create a monitoring watch on various HumanOS entities, ensuring vigilant oversight and preemptive action. By tracking events, sources, or patterns, it provides a strategic advantage in maintaining operational integrity and safety.

Request Body schema: application/json
required
target_ref
required
string

The reference to the target entity or pattern to watch.

watch_kind
required
string
Enum: "entity" "source" "event_type" "pattern"

The kind of watch to establish, dictating the monitoring scope.

owner_ref
string

Identifier for the owner of the watch, defaulting to the context's delegation if not provided.

scope
string

Scope of the watch, typically 'org' for organization-wide.

schedule
object

JSON object representing the watch's scheduling parameters.

Responses

Request samples

Content type
application/json

Creating a watch for monitoring a specific event type within an organization.

{
  • "target_ref": "event_type:invoice_processed",
  • "watch_kind": "event_type",
  • "owner_ref": "did:example:123456789abcdefghi",
  • "scope": "org",
  • "schedule": {
    }
}

Response samples

Content type
application/json
null

Retrieve active HumanOS watch entries

In the HumanOS, watches are guardians of the orchestration protocol, monitoring vast landscapes of tasks and capabilities. This endpoint reveals a curated list of these sentinels, filtered by your organizational identity, ensuring only those you are permitted to view are displayed. The power of delegation and oversight is at your fingertips, enabling you to manage the intricate web of tasks with precision.

Responses

Response samples

Content type
application/json

Retrieve the list of watches currently monitored by Acme Corp, showing task oversight in action.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Evaluate a Watch Cycle for Feedback

In the intricate dance between humans and AI, feedback is the music. This endpoint lets organizations capture and store evaluation feedback for a specific watch cycle, enhancing the transparency and auditability of AI decisions. By anchoring an evaluation in the distributed ledger, you ensure that your AI's decisions are not only accountable but also improvable.

Request Body schema: application/json
required
provenance_id
string

An optional identifier for provenance tracking, providing a cryptographic link to prior events.

Responses

Request samples

Content type
application/json

An evaluation including a provenance pointer for enhanced traceability

{
  • "provenance_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "evaluation_feedback_id": "789e4567-e89b-12d3-a456-426614174111",
  • "watch_id": "watch123",
  • "org_did": "did:example:acme",
  • "evaluated_at": "2023-10-01T12:34:56Z",
  • "provenance_pointer": "123e4567-e89b-12d3-a456-426614174000"
}

Retrieve details of a specific watch

Discover the intricate details of a specific HumanOS watch. This endpoint reveals how tasks are orchestrated within your organization by fetching comprehensive data about a watch, including its status and schedule. It's a lens into understanding how tasks are managed and monitored, ensuring the right skills are applied at the right time.

Responses

Response samples

Content type
application/json

An example showing the details of a specific watch.

{
  • "watch_id": "watch123",
  • "org_did": "did:human:org:acme",
  • "target_ref": "task:invoice-processing",
  • "watch_kind": "realtime",
  • "owner_ref": "agent:john.doe",
  • "scope": "organization",
  • "schedule": "0 0 * * *",
  • "status": "active",
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-02T12:00:00Z"
}

Create a new HUMAN artifact

This endpoint allows organizations to craft and store digital artifacts, defining their type and metadata for enhanced provenance tracking. It empowers teams to maintain a transparent history of digital creations, facilitating AI collaboration with human oversight.

Request Body schema: application/json
required
artifact_type
required
string

The type of the artifact, must be a valid dot-namespace kind.

metadata
object

Metadata specific to the artifact kind.

owner_ref
string

Reference to the owner of the artifact.

schema_ref
string

Reference to the schema applicable to the artifact.

capture_id
string

Identifier for the capture session, if applicable.

title
string

A brief title for the artifact.

body
object

The actual content of the artifact.

media_type
string

Media type of the artifact content.

body_storage_ref
string

Reference for storage of large artifact content.

production
object

Production-related metadata.

created_by
object

Actor reference for the entity creating the artifact.

provenance_summary
string

A summary of the provenance action.

Responses

Request samples

Content type
application/json

This example demonstrates creating a basic artifact with essential fields.

{
  • "artifact_type": "document.invoice",
  • "metadata": {
    },
  • "owner_ref": "did:example:123456",
  • "title": "Q3 Financial Report",
  • "body": {
    },
  • "media_type": "application/json"
}

Response samples

Content type
application/json
{
  • "artifact_id": "art-xyz123",
  • "org_did": "did:example:123456",
  • "artifact_type": "document.invoice"
}

Retrieve a list of artifacts

Delve into the HUMAN platform's vast repository of artifacts, each a testimony to the collective intelligence of humans and AI. This endpoint lets you navigate through a curated list of organizational artifacts, filtered by type and lifecycle state, empowering you to track the evolution of human and AI collaboration.

Responses

Response samples

Content type
application/json

Retrieve a list of artifacts belonging to the Acme Corporation, filtered by type and state.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Retrieve Artifact with Provenance Details

Uncover the history and details of an artifact within the HUMAN platform. This endpoint provides not only the artifact's core data but also its provenance and revision chain, ensuring a comprehensive understanding of its journey and transformations. It's designed to empower users with transparency and traceability, crucial for trust in Human-AI orchestration.

Responses

Response samples

Content type
application/json

Retrieve artifact details for Acme Corp's invoice processing system.

{
  • "artifact_id": "artifact-12345",
  • "name": "Invoice Processing System",
  • "description": "Handles the processing of invoices for Acme Corp.",
  • "created_at": "2023-10-01T12:00:00Z",
  • "provenance": [
    ],
  • "revision_chain": [
    ]
}

Retrieve artifact explanation bundle

Dive deep into the workings of your AI artifact with this endpoint. It unveils the intricate policies and learning adaptations that shape your artifact's lifecycle, providing insights into the AI decisions and their provenance. This is where AI transparency meets operational intelligence.

Responses

Response samples

Content type
application/json

An insightful explanation of an artifact belonging to Acme Corp, revealing its state and the decisions influencing it.

{
  • "summary": "Artifact 12345 is in state active. Effective HumanOS org policy (P8) is applied as hos_pol:acme:2023-10-05T14:48:00Z.",
  • "factors": [
    ],
  • "related_work_refs": [
    ],
  • "confidence": {
    },
  • "learning": {
    }
}

Submit Feedback Event for HumanOS

This endpoint lets organizations send feedback events to HumanOS, enabling a collaborative environment between human efforts and AI. By doing so, it ensures that the AI is continuously learning and evolving based on real-world inputs and organizational policies.

Request Body schema: application/json
required
scope
string

The scope of the feedback event, defaults to 'user'.

payload_type
required
string

The type of feedback event being submitted. Must be a known HumanOS v1 feedback event type.

passport_did
string

The Passport DID associated with the feedback event.

target_kind
string

The kind of target entity for the feedback.

target_id
string

The identifier of the target entity.

payload
object

Additional data related to the feedback event.

Responses

Request samples

Content type
application/json

A simple example of submitting a feedback event with mandatory fields.

{
  • "scope": "team",
  • "payload_type": "task_completion",
  • "passport_did": "did:human:abcd1234",
  • "target_kind": "task",
  • "target_id": "task-5678",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "feedback_id": "evt-9012",
  • "org_did": "did:org:acme123",
  • "scope": "team",
  • "payload_type": "task_completion",
  • "created_at": "2023-10-01T12:15:00Z"
}

Retrieve feedback events for an organization

Explore the trail of feedback events that have shaped the human-AI collaboration within your organization. This endpoint unravels the narrative of how feedback flows through the HUMAN ecosystem, tracking its origins and destinations.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Verify the provenance of an artifact

Unravel the intricate history of your digital artifacts with our provenance verification. This endpoint allows organizations to validate the integrity and authenticity of their artifacts by checking their provenance hashes, ensuring trust and transparency in the HUMAN platform.

Responses

Response samples

Content type
application/json
{
  • "artifact_id": "123e4567-e89b-12d3-a456-426614174000",
  • "verified": true,
  • "message": "Provenance verified successfully."
}

Revise existing artifact for enhancement

Revise an existing artifact to incorporate updates or corrections, ensuring the artifact evolves with your organization's needs. This endpoint facilitates the continuous improvement of your digital assets, promoting agility and precision in Human-AI orchestration.

Request Body schema: application/json
required
title
string

Optional new title for the artifact.

metadata
object

Optional metadata specific to the artifact's kind.

body
object

The content of the artifact, constrained by size.

media_type
string

The media type of the artifact content.

summary
string

A brief summary of the changes made during the revision.

Responses

Request samples

Content type
application/json

An example of revising an artifact related to invoice processing in the 'acme' organization.

{
  • "title": "Updated Invoice Processing",
  • "metadata": {
    },
  • "body": {
    },
  • "media_type": "application/json",
  • "summary": "Improved step-by-step guide for invoice processing."
}

Response samples

Content type
application/json
null

Retrieve Effective Agent Policy

Unlock the power of HumanOS by accessing the effective policy for a specified agent. This endpoint helps organizations monitor and enforce skill progress gates, ensuring every agent adheres to the orchestrated protocol.

Responses

Response samples

Content type
application/json
{
  • "agent_id": "agent123",
  • "org_did": "did:human:org:acme",
  • "policy_json": {
    }
}

Retrieve Organization Workforce Routing Config

Explore the intricate orchestration of human and AI collaboration within an organization. This endpoint unveils the current routing configuration, vital for ensuring tasks are allocated efficiently and safely. It's your window into the dynamic core of HumanOS task routing.

Responses

Response samples

Content type
application/json

Example of a successful retrieval of routing configuration for an organization.

{
  • "org_did": "did:human:acme",
  • "config": {
    },
  • "updated_at": "2023-10-01T12:34:56Z"
}

Invoke an extension's capability for action

Unlock the potential of your organization's installed extensions by invoking specific capabilities. This endpoint is the gateway to extending functionality, allowing you to orchestrate tasks and actions with precision and control. It exists to seamlessly integrate and activate the diverse capabilities within your distributed AI systems.

Request Body schema: application/json
required
capability
required
string

The capability to be invoked, identified by a URI

action
string

The action to perform using the capability

params
object

Parameters required for the action

Responses

Request samples

Content type
application/json

Invoke the 'processInvoice' capability to automate invoice handling for the 'acme' organization.

{
  • "capability": "capability://acme/invoice/process",
  • "action": "process",
  • "params": {
    }
}

Response samples

Content type
application/json
null

Suggest remediation for an incident

This endpoint crafts a thoughtful remediation suggestion for a given incident, weaving together AI predictions and human insights. It empowers organizations to address incidents with precision, ensuring safety and compliance through seamless task orchestration.

Request Body schema: application/json
required
enqueue_agent_trigger
boolean

Flag to trigger an agent if true.

Responses

Request samples

Content type
application/json
Example

A request to suggest remediation without agent trigger.

{
  • "enqueue_agent_trigger": false
}

Response samples

Content type
application/json
{
  • "incident_id": "12345",
  • "mode": "automatic",
  • "steps": [
    ]
}

Route tasks with HumanOS AI orchestration

This endpoint is a gateway to orchestrate tasks efficiently using the HumanOS routing capabilities. By combining AI-driven insights with human skills, it ensures tasks are assigned to the most suitable agents. This promotes seamless interaction between humans and AI, optimizing task outcomes.

Request Body schema: application/json
required
task_id
required
string

Unique identifier for the task

task_type
required
string

Type of task to be routed

priority
string
Enum: "low" "medium" "high"

Priority level of the task

metadata
object

Additional data related to the task

Responses

Request samples

Content type
application/json

Routing a high-priority customer support task

{
  • "task_id": "task-12345",
  • "task_type": "customer_support",
  • "priority": "high",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "status": "routed",
  • "agent_id": "agent-98765"
}

Route fraud case for human intervention

In the intricate dance of AI and human collaboration, this endpoint orchestrates the routing of potential fraud cases to human agents for further investigation. It ensures that suspicious activities don't slip through the cracks of automation, safeguarding the integrity of your operations.

Request Body schema: application/json
required
case_ref
required
string

A unique reference for the fraud case

Responses

Request samples

Content type
application/json

Routing a fraud case with a unique reference to human agents.

{
  • "case_ref": "fraud_case_12345"
}

Response samples

Content type
application/json
{
  • "routing_id": "cp_frt_67890",
  • "case_ref": "fraud_case_12345",
  • "routing_decision": "route_to_human",
  • "reason": "fraud_investigation_default",
  • "fourth_law_triggered": true,
  • "recorded_at": "2023-10-11T08:30:00Z"
}

Assess risk of a routed task

Uncover the hidden risks associated with a specific task routed through the HUMAN platform. This endpoint provides a risk score for a task, ensuring that potential issues are flagged early, allowing for proactive management and AI safety.

Responses

Response samples

Content type
application/json

Retrieve risk details for routing ID 12345.

{
  • "routing_id": "12345",
  • "agent_did": "did:human:acme",
  • "task_description": "Invoice processing for client XYZ",
  • "risk_score": 7.5,
  • "scored_at": "2023-10-05T14:48:00.000Z"
}

Retrieve structured policy summaries

Discover the governance of your organization through HUMAN's curated policy summaries. This endpoint allows organizations to gain insights into their policy landscape by fetching structured overviews, helping you navigate and enhance your task orchestration with AI safety.

Responses

Response samples

Content type
application/json

Acme Corp retrieves policy summaries to ensure compliance and operational efficiency.

{
  • "data": [
    ],
  • "limit": 20,
  • "cursorField": "policy_id",
  • "hasMore": false
}

Create a structured HumanOS policy

Define structured policies within the HumanOS to govern task execution with precision. This endpoint empowers organizations to craft policies that ensure AI safety and task orchestration fidelity. By harnessing the protocol, you create robust governance frameworks that align with organizational objectives.

Request Body schema: application/json
required
name
required
string

A unique name for the policy.

required
object

The policy document detailing rules and parameters.

team_id
string

Identifier for the team the policy applies to.

agent_did
string

Decentralized Identifier for the agent responsible for the policy.

active
boolean

Flag indicating if the policy is active.

Responses

Request samples

Content type
application/json

This example demonstrates creating a new policy for invoice processing.

{
  • "name": "Invoice Processing Policy",
  • "policy": {
    },
  • "team_id": "team-1234",
  • "agent_did": "did:human:agent-5678",
  • "active": true
}

Response samples

Content type
application/json
{
  • "policy_id": "policy-12345",
  • "name": "Invoice Processing Policy",
  • "version": 1,
  • "active": true,
  • "created_at": "2023-10-30T14:12:00Z"
}

Delete a structured policy by ID

In the intricate dance of task automation, sometimes a policy outlives its usefulness. This endpoint allows organizations to gracefully retire a structured policy, ensuring that their orchestration remains agile and adaptive. By removing outdated policies, organizations can streamline their operations and maintain a clean, efficient task routing system.

Responses

Response samples

Content type
application/json
null

Fetch structured policy details by ID

Retrieve intricate policy details tailored to your organization's dynamics. This endpoint empowers organizations to understand and manage their task routing policies effectively, ensuring alignment with their AI safety protocols.

Responses

Response samples

Content type
application/json

Represents a policy for handling invoices within the 'acme' organization.

{
  • "policy_id": "a123b456-c789-0123-d456-789e012f3456",
  • "name": "Invoice Processing",
  • "policy": {
    },
  • "active": true,
  • "version": 2,
  • "team_id": "f7890123-4567-89ab-cdef-0123456789ab",
  • "agent_did": "did:human:agents:acme-processor",
  • "created_at": "2023-01-15T08:00:00Z",
  • "updated_at": "2023-09-20T14:30:00Z"
}

Update structured HumanOS policy

This endpoint empowers organizations to update their structured policies within the HumanOS task routing system. By maintaining accurate and current policy definitions, organizations can ensure AI safety and compliance. This operation is crucial for organizations like 'acme' who need to adapt their policy frameworks promptly.

Request Body schema: application/json
required
name
string

A descriptive name for the policy.

object

The new policy document to validate and apply.

active
boolean

Indicates whether the policy should be active.

Responses

Request samples

Content type
application/json

An example of updating a policy with a new name and active status.

{
  • "name": "Updated Invoice Processing Policy",
  • "policy": {
    },
  • "active": true
}

Response samples

Content type
application/json
{
  • "policy_id": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "Updated Invoice Processing Policy",
  • "active": true,
  • "version": 2,
  • "updated_at": "2023-10-01T12:34:56Z"
}

Validate human policy structure

In the ever-evolving landscape of AI collaborations, ensuring that policies are structured correctly is paramount. This endpoint invites organizations to validate their policy documents, ensuring they meet the cryptographic standards required for secure, efficient AI orchestration. By confirming the validity of these policies, organizations can trust in a seamless integration with HUMAN's distributed ledger.

Request Body schema: application/json
required
required
object

The policy document to validate.

Responses

Request samples

Content type
application/json

A sample policy document from Acme Corp undergoing validation.

{
  • "policy": {
    }
}

Response samples

Content type
application/json
{
  • "valid": true
}

Route batch tasks through HumanOS

The batch-route endpoint empowers organizations to efficiently direct multiple tasks through HumanOS, leveraging AI-driven orchestration for safe and effective task execution. This endpoint underlines the platform's commitment to scalability and precision, optimizing the management of up to 50 tasks in a single request.

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json

Submitting a batch of tasks for AI routing within 'acme' organization.

{
  • "tasks": [
    ]
}

Response samples

Content type
application/json

All tasks in the batch are successfully processed.

{
  • "results": [
    ],
  • "batch_size": 2
}

Retrieve Payment Boundaries for Actions

Dive into the realm of HumanOS task routing by exploring payment boundaries for specific actions. This endpoint helps organizations understand financial limits tied to their actions, ensuring AI interactions remain within budgetary constraints.

Responses

Response samples

Content type
application/json

An example where the 'acme' organization checks the payment boundary for processing invoices.

{
  • "action": "process_invoice",
  • "limit": 1000,
  • "currency": "USD"
}

Retrieve audit events from HumanOS

Unveil the intricate dance of actions within your organization by exploring the audit trail maintained by HumanOS. This endpoint allows you to sift through the past, examining the orchestration of tasks and decisions made by both humans and AI. Whether you're tracking down anomalies or ensuring compliance, these records hold the key.

Responses

Response samples

Content type
application/json

Retrieve the latest audit events for monitoring task execution

{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "eyJfaHVtYW5vc19hdWRpdF9zb3J0IjoiY3JlYXRlZF9hdCIsImlkIjoxMDAwMX0="
}

Retrieve routing decision details

Discover the intricate journey of a task within HUMAN's AI orchestration. This endpoint illuminates the path a task takes, revealing the decision-making intricacies and outcomes. Tracking the provenance of AI-driven processes is crucial for transparency and trust.

Responses

Response samples

Content type
application/json

Shows a successful retrieval of routing information for a task

{
  • "routing_id": "routing-123",
  • "task_id": "task-456",
  • "task_type": "invoice-processing",
  • "status": "completed",
  • "confidence": 0.95,
  • "fourth_law_triggered": false,
  • "routing_decision": "approved",
  • "pipeline_success": true,
  • "request_payload": {
    },
  • "response_payload": {
    },
  • "pipeline_stages": [
    ],
  • "created_at": "2023-10-04T14:48:00Z"
}

Create a new escalation rule

In the HUMAN realm, routing tasks safely and efficiently often demands escalation. This endpoint empowers organizations to define rules that trigger when conditions warrant human intervention, ensuring seamless task management and AI oversight.

Request Body schema: application/json
required
name
required
string

A unique name for the escalation rule.

conditions
object

Conditions under which the escalation rule is triggered.

Responses

Request samples

Content type
application/json

An example rule that triggers when default conditions are met.

{
  • "name": "Urgent Task Escalation",
  • "conditions": {
    }
}

Response samples

Content type
application/json

A successful response indicating a new rule was created.

{
  • "rule_id": "hos_rule_123456",
  • "name": "Urgent Task Escalation",
  • "created_at": "2023-10-01T12:00:00Z"
}

Manually escalate tasks for human oversight

In the dynamic realm of HUMAN's orchestration, this endpoint enables organizations to manually escalate tasks requiring human intervention. It ensures that critical tasks are handled with the attention they demand, combining the power of AI with the wisdom of human judgment.

Request Body schema: application/json
required
reason
required
string

The reason for escalating this task, providing context for human intervention.

task_type
string

The type of task being escalated, helping route to the appropriate human agent.

routing_id
string

An identifier for the routing of the task, ensuring precise tracking.

object

Additional context for the escalation, allowing for a richer understanding of the situation.

Responses

Request samples

Content type
application/json

Escalating an invoice processing task due to complex discrepancy.

{
  • "reason": "Discrepancy in invoice data requires human review.",
  • "task_type": "invoice_processing",
  • "routing_id": "task-12345",
  • "context": {
    }
}

Response samples

Content type
application/json
null

Evaluate HumanOS task safety checks

This endpoint assesses whether a specific action within a given domain complies with the organization's HumanOS safety policies. By evaluating these actions, HumanOS ensures that tasks are performed within the ethical and procedural boundaries set by the organization, protecting both human and AI participants.

Request Body schema: application/json
required
domain
required
string
Default: "general"

Domain of the action, e.g., 'finance' or 'general'

action
required
string
Default: "unknown"

Specific action to be evaluated, e.g., 'processInvoice'

Responses

Request samples

Content type
application/json

Check safety for processing an invoice in the finance domain.

{
  • "domain": "finance",
  • "action": "processInvoice"
}

Response samples

Content type
application/json
{
  • "allowed": true,
  • "domain": "finance",
  • "action": "processInvoice",
  • "reasons": [
    ],
  • "reviewed_at": "2023-10-01T12:34:56Z"
}

Retrieve HumanOS Safety Configuration

Uncover the safety protocols that guide HumanOS in safeguarding your organization’s tasks. This endpoint provides an organization-specific configuration that aligns AI task routing with safety policies, ensuring secure and efficient operations.

Responses

Response samples

Content type
application/json

Acme Corporation's safety configuration for HumanOS task routing.

{
  • "config": {
    },
  • "org_scoped": true
}

Retrieve task provenance details

Explore the intricate journey of a task within the HUMAN ecosystem through its provenance data. This endpoint weaves a narrative of how tasks evolve, ensuring transparency and accountability in AI-human collaboration.

Responses

Response samples

Content type
application/json

Fetching the provenance details for task A1 belonging to org acme.

{
  • "routing_id": "1234-5678-9012",
  • "task_id": "acme:task-a1",
  • "routing_summary": {
    },
  • "pipeline_stages": {
    },
  • "provenance_graph": {
    }
}

Retrieve agent performance metrics

Discover how an agent has been performing over time, tracked by audit events. This endpoint helps organizations analyze AI agent activity to ensure efficient task handling and compliance with operational standards.

Responses

Response samples

Content type
application/json

Performance metrics for agent 'agent123' over the past 30 days.

{
  • "agent_id": "agent123",
  • "period": "30d",
  • "events_recorded": 150,
  • "rollup": "audit_payload_agent_id"
}

Retrieve Effective HumanOS Policy

Discover the confluence of organizational directives within the HUMAN platform. This endpoint reveals the effective HumanOS policy, interwoven with organizational overlays, offering insights into AI task governance and safety protocols.

Responses

Response samples

Content type
application/json

Fetching the effective HumanOS policy for Acme Corporation.

{
  • "policy_version": "1.4.5",
  • "fourth_law_confidence_threshold": 0.85,
  • "learning_requires_approval": true,
  • "learning": {
    },
  • "merged_policy": {
    },
  • "policy_resolution": {
    }
}

Update or create organizational policy

This endpoint empowers administrators to seamlessly update or create policies for their organization, ensuring that the latest configurations are always in place. By leveraging a cryptographic identity (Passport), the HUMAN protocol guarantees that only authorized users can manage these critical settings.

Request Body schema: application/json
required
policy_json
required
object

The JSON object representing the organization's policy settings. It acts as a partial overlay to merge with existing policies.

Responses

Request samples

Content type
application/json

This example demonstrates updating the policy document for Acme Corporation, adding a new billing rule.

{
  • "policy_json": {
    }
}

Response samples

Content type
application/json
{
  • "org_did": "did:human:acmeCorp123",
  • "merged_policy": {
    },
  • "updated_at": "2023-10-23T14:55:00Z"
}

Update Team Policy Overlay

Seamlessly merge new AI safety policies into your team's existing configuration, ensuring that your organization's human-AI orchestration remains both agile and robust. This endpoint empowers administrators by allowing them to update team-specific capabilities, harnessing the strength of distributed ledger technology for impeccable provenance tracking.

Request Body schema: application/json
required
policy_json
required
object

A JSON object representing the policy overlay to merge into the existing team policy.

Responses

Request samples

Content type
application/json

An example showing how to update the invoicing policy for a team within an organization.

{
  • "policy_json": {
    }
}

Response samples

Content type
application/json
{
  • "org_did": "did:example:acme",
  • "team_id": "team-1234",
  • "merged_policy": {
    },
  • "updated_at": "2023-12-01T12:34:56Z"
}

Update User's Policy Overlay

Empower users to tailor their HumanOS task orchestration by updating their policy overlays. This endpoint allows a delegation to redefine how tasks are routed, ensuring that the AI respects personalized rules and preferences.

Request Body schema: application/json
required
policy_json
required
object

A partial user policy overlay defining task routing rules.

Responses

Request samples

Content type
application/json

An example showing how to update task routing preferences to prioritize safety checks.

{
  • "policy_json": {
    }
}

Response samples

Content type
application/json
{
  • "org_did": "did:example:123456789abcdefghi",
  • "passport_did": "did:example:abcdef123456789",
  • "merged_policy": {
    },
  • "updated_at": "2023-10-15T12:30:00Z"
}

Update User Policy with Passport DID

Enhance user experience by updating policy overlays for users identified by their Passport DID. This endpoint empowers administrators to tailor AI safety and task routing policies, ensuring the HUMAN platform aligns with organizational needs.

Request Body schema: application/json
required
policy_json
required
object

A JSON object that represents the user's policy settings.

Responses

Request samples

Content type
application/json

Example of a policy update for user tasks and AI interaction.

{
  • "policy_json": {
    }
}

Response samples

Content type
application/json
{
  • "org_did": "org:example-corp",
  • "passport_did": "did:human:123456789abcdefghi",
  • "merged_policy": {
    },
  • "updated_at": "2023-10-15T12:34:56Z"
}

Retrieve learning pointers with pagination

Explore the learning index to discover pointers associated with your organization's skillset. This endpoint serves as the navigator through the knowledge network, providing entries that match your criteria. Perfect for organizations aiming to streamline their AI-enabled learning pathways.

Responses

Response samples

Content type
application/json

A list of learning pointers for the 'acme' organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": true,
  • "cursorFields": [
    ],
  • "totalCount": null
}

Retrieve learning proposals with pagination

In a world where human expertise meets AI orchestration, learning proposals are the blueprints for adaptive growth. This endpoint allows organizations to fetch these proposals, ensuring they harness the right skills at the right time. Pagination and status filtering provide fine-tuned control over the data flow.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Draft a new learning proposal

Create a draft proposal to orchestrate human learning tasks with AI safety. This endpoint empowers organizations to define and track skills development initiatives, ensuring each proposal is routed efficiently while maintaining a secure and auditable trail.

Request Body schema: application/json
required
proposal_kind
required
string

The type of learning proposal being created.

scope
string

The scope of the proposal, defaults to 'org'.

passport_did
string

The cryptographic identity of the passport associated with the proposal.

approval_request_id
string

ID for the approval request, if applicable.

source_feedback_ids
Array of integers

Identifiers for feedback sources related to the proposal.

expires_at
string <date-time>

The expiration timestamp for the proposal.

payload
object

Additional data associated with the proposal.

object (LearningExplainMetadata)

Optional explain metadata on learning proposals (POST /v1/humanos/learning/proposals) and embedded in humanos_tuning_actions.payload after apply. Validated with LearningExplainMetadataSchema in @human/humanos; unknown keys are stripped.

Responses

Request samples

Content type
application/json

A simple draft proposal for a new training module.

{
  • "proposal_kind": "new_training_module",
  • "scope": "org",
  • "passport_did": "did:human:123456789abcdefghi",
  • "approval_request_id": "approval-6789",
  • "source_feedback_ids": [
    ],
  • "expires_at": "2023-12-31T23:59:59Z",
  • "payload": {
    },
  • "explain": {
    }
}

Response samples

Content type
application/json
{
  • "proposal_id": "lrp-20231001-abc123",
  • "org_did": "did:human:org123",
  • "status": "draft",
  • "proposal_kind": "new_training_module",
  • "payload": {
    },
  • "explain": {
    },
  • "approval_request_id": "approval-6789",
  • "source_feedback_ids": [
    ],
  • "expires_at": "2023-12-31T23:59:59Z",
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-01T12:00:00Z"
}

Retrieve a specific learning proposal.

Fetch details of a learning proposal for an organization in the HUMAN network, empowering you to track AI skill enhancements with precision and accountability. Understand the status, scope, and feedback of your proposals at a glance, ensuring your initiatives align with organizational goals.

Responses

Response samples

Content type
application/json

An example of a learning proposal retrieved for the Acme Corp organization.

{
  • "proposal_id": "abc123",
  • "org_did": "did:human:acme",
  • "passport_did": "did:human:john.doe",
  • "scope": "AI skill enhancement",
  • "status": "approved",
  • "proposal_kind": "training",
  • "payload": {
    },
  • "explain": {
    },
  • "approval_request_id": "req-456def",
  • "source_feedback_ids": [
    ],
  • "expires_at": "2024-01-01T00:00:00Z",
  • "created_at": "2023-08-15T12:00:00Z",
  • "updated_at": "2023-09-01T08:30:00Z"
}

Update Learning Proposal Status

Navigate the complex journey of transforming a learning proposal's status with precision. This endpoint empowers you to orchestrate seamless transitions, ensuring that proposals progress through the appropriate lifecycle stages while maintaining compliance with server-enforced status transitions.

Request Body schema: application/json
required
status
required
string
Enum: "draft" "pending_review" "approved" "rejected" "applied" "rolled_back"

The new status for the proposal.

approval_request_id
string or null

Optional ID for an approval request related to this status change.

Responses

Request samples

Content type
application/json

This example demonstrates updating a proposal status from 'draft' to 'pending_review' with an associated approval request.

{
  • "status": "pending_review",
  • "approval_request_id": "approval-1234"
}

Response samples

Content type
application/json
null

Apply an approved learning proposal

In the dynamic world of HumanOS, this endpoint breathes life into your approved learning proposals, transforming potential into action. By applying an approved proposal, you propel your organization into the future, harnessing the power of adaptive learning to stay ahead in the ever-evolving landscape.

Responses

Response samples

Content type
application/json

A successful application of an approved learning proposal.

{
  • "proposal_id": "prop123456",
  • "status": "applied",
  • "tuning_action_id": "tun789012",
  • "action_type": "set_preference",
  • "scope": "org",
  • "tuning_expires_at": "2023-12-31T23:59:59Z",
  • "created_at": "2023-11-01T12:00:00Z"
}

Roll back a learning proposal

This endpoint empowers organizations to roll back previously applied learning proposals within HumanOS. By reversing an applied proposal, the system ensures flexibility and adaptability in dynamic environments, allowing for strategic pivots when necessary.

Responses

Response samples

Content type
application/json

Example of a successful rollback of a learning proposal.

{
  • "proposal_id": "abc123",
  • "status": "rolled_back",
  • "compensating_tuning_action_id": "tun567",
  • "scope": "org",
  • "superseded_tuning_action_id": "tun789"
}

Infer learning proposals from feedback

Harness the power of collective intelligence by transforming feedback into actionable learning proposals. This endpoint analyzes recent feedback events within your organization to suggest improvements, helping you stay ahead in a rapidly evolving landscape.

Request Body schema: application/json
required
limit
integer [ 1 .. 100 ]

Maximum number of feedback events to process. Defaults to 20 if not specified.

Responses

Request samples

Content type
application/json

Request to process up to 30 feedback events.

{
  • "limit": 30
}

Response samples

Content type
application/json
{
  • "org_did": "did:example:123456789abcdef",
  • "drafts": [
    ],
  • "feedback_rows_considered": 30
}

Transcribe audio into intent brief

Transform spoken words into actionable intent briefs, enabling seamless AI orchestration. This endpoint captures and decodes audio snippets, creating structured insights that drive workflow automation.

Request Body schema: application/json
required
audio_base64
string

Base64-encoded audio file to be transcribed.

transcript
string

Optional pre-existing transcription of the audio.

source_surface
string
Enum: "companion" "control_plane" "workflow_designer" "agent_builder"

Origin surface where the request was made.

Responses

Request samples

Content type
application/json

Demonstrating transcription of a Base64 audio input captured from companion surface.

{
  • "audio_base64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA... (truncated)",
  • "source_surface": "companion"
}

Response samples

Content type
application/json
{
  • "brief": {
    },
  • "needs_clarification": false,
  • "clarification_questions": [ ]
}

Retrieve eligibility snapshot for opportunities

In the fast-paced world of human-AI collaboration, understanding your eligibility for various opportunities is crucial. This endpoint allows users to fetch the latest eligibility snapshot for a given opportunity type based on their cryptographic identity, ensuring informed decision-making and efficient task allocation.

Responses

Response samples

Content type
application/json

Shows eligibility status for a workforce task based on the latest snapshot.

{
  • "passport_did": "did:human:acme-john-doe",
  • "opportunity_type": "workforce_task",
  • "eligibility_status": "eligible",
  • "computed_at": "2023-10-01T12:34:56Z"
}

Retrieve evidence audit by routing decision

Dive into the past decisions of our AI orchestrated tasks with this endpoint. By querying the audit trail of routing decisions, you gain insights into task assignments, ensuring transparency and accountability in AI-human collaborations.

Responses

Response samples

Content type
application/json

An audit record showing how a task was routed for the given decision ID.

{
  • "evidence": {
    }
}

Agent Orchestration

Invoke Agent via Capability or Workflow

The Unified Human-AI Orchestration Gateway empowers organizations to seamlessly orchestrate tasks across human and AI agents. By leveraging capability URIs, agent URIs, or workflow capability steps, users can route tasks dynamically and ensure AI safety through HumanOS. This endpoint is the backbone of intelligent task routing, ensuring tasks reach the most capable executor.

Request Body schema: application/json
required
One of
capability
required
string^capability://

Capability URI for task routing

async
boolean

Whether the invocation should be asynchronous

object

Input parameters for the agent

Responses

Request samples

Content type
application/json
Example

Example invoking an agent using a capability URI.

{
  • "capability": "capability://org123/email.read",
  • "async": false,
  • "input": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "routing": {
    },
  • "metadata": {
    },
  • "action_receipt": {
    }
}

Execution

Poll execution status asynchronously

Retrieve the current status of an execution task. This endpoint enables clients to track the progress of tasks managed by HUMAN's orchestration layer, ensuring transparent and reliable updates without blocking operations.

Responses

Response samples

Content type
application/json
Example
{
  • "execution_id": "exec_abc123",
  • "status": "processing",
  • "created_at": "2025-11-25T10:30:00.000Z",
  • "updated_at": "2025-11-25T10:30:05.000Z",
  • "started_at": "2025-11-25T10:30:01.000Z",
  • "message": "Execution is currently being processed"
}

Execute a workflow in the workforce system

Embark on a seamless journey of workflow execution within the HUMAN platform. This endpoint breathes life into your workflows, orchestrating tasks with precision and tracking their progress meticulously. It serves as the beating heart of operations, ensuring that tasks are not only executed but also monitored for efficiency and success.

Request Body schema: application/json
required
input_data
required
Array of objects

Array of data items to process within the workflow

priority
string
Enum: "high" "normal" "low"

Priority level of the execution

Responses

Request samples

Content type
application/json

Executing a workflow with standard priority

{
  • "input_data": [
    ],
  • "priority": "normal"
}

Response samples

Content type
application/json
null

Resume paused workflow for active processing

This endpoint is the key to unlocking potential in workflows that have hit a pause. Imagine the gears of a complex machine grinding to a halt awaiting approval—this endpoint breathes life back into them. By resuming paused nodes within a workflow's DAG, it ensures that no opportunity for progress is lost.

Responses

Response samples

Content type
application/json
null

Retrieve execution details by ID

Unlock the insights of your task orchestration by fetching detailed execution data through this endpoint. It bridges the gap between human and AI efforts, providing a comprehensive view of your operation's journey from start to finish. Trace every step, understand the status, and connect with the agents involved, making this endpoint your window into the orchestration process.

Responses

Response samples

Content type
application/json

Fetching an execution record for Acme Corp, including details of a linked asynchronous task.

{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "execution_id": "exec-789",
  • "org_did": "did:human:acme-corp",
  • "incident_id": "incident-001",
  • "surface": "web",
  • "status": "completed",
  • "started_at": "2023-10-01T08:00:00Z",
  • "completed_at": "2023-10-01T09:00:00Z",
  • "metadata": {
    },
  • "created_at": "2023-09-28T07:00:00Z",
  • "updated_at": "2023-10-01T09:05:00Z",
  • "async_execution": {
    }
}

Approvals

Retrieve pending approval requests

Navigate the intricate web of task approvals with this endpoint, designed to orchestrate queries across the HUMAN platform. Whether you're an approver, requester, or an automated task agent, this endpoint provides a streamlined view of approval requests, ensuring transparency and traceability in task management.

Responses

Response samples

Content type
application/json

Example of a successful response with multiple approval requests

{
  • "data": [
    ],
  • "limit": 10,
  • "next_cursor": "cursor_67890"
}

Retrieve detailed approval request information

Dive into the details of a specific approval request, uncovering the journey and decisions it entails. This endpoint enables tracking and understanding of task approval processes, ensuring transparency and accountability within the HUMAN platform.

Responses

Response samples

Content type
application/json

An organization 'acme' is reviewing an approval request for task routing.

{
  • "id": "approval_12345",
  • "task_id": "task_67890",
  • "agent_id": "agent_001",
  • "requester_passport_id": "passport_abc123",
  • "approver_passport_id": "passport_xyz789",
  • "action_description": "Request to approve invoice processing",
  • "risk_level": "medium",
  • "risk_factors": [
    ],
  • "alternatives": [
    ],
  • "request_data": {
    },
  • "escalation_schema": {
    },
  • "status": "pending",
  • "response": null,
  • "response_comment": null,
  • "responded_at": null,
  • "responded_by": null,
  • "modified_params": null,
  • "delegated_to": null,
  • "override_action": null,
  • "conversation_id": "conv_7890",
  • "created_at": "2023-10-01T10:00:00Z",
  • "expires_at": "2023-10-15T10:00:00Z",
  • "updated_at": "2023-10-01T10:05:00Z",
  • "provenance_id": "prov_123456"
}

Respond to an approval request

In the ever-evolving landscape of human-AI collaboration, responding to approval requests ensures that tasks flow seamlessly between agents and AI. This endpoint empowers users to make pivotal decisions—approving, rejecting, or delegating—thereby maintaining the dynamic equilibrium of the HUMAN Protocol.

Request Body schema: application/json
required
decision
required
string
Enum: "approved" "approved_with_modifications" "rejected" "delegated" "overridden"

The decision made on the approval request.

comment
string

Optional comment providing additional context for the decision.

modified_params
object

Parameters modified during approval.

delegate_to
string

DID of the agent to whom the task is delegated, if applicable.

override_action
string

Action to override current settings, if necessary.

Responses

Request samples

Content type
application/json

Approving a request with a comment and modifications.

{
  • "decision": "approved_with_modifications",
  • "comment": "Approved with minor parameter updates",
  • "modified_params": {
    }
}

Response samples

Content type
application/json
null

Cancel a Pending Approval Request

In the dynamic world of approval workflows, sometimes decisions change. This endpoint empowers users to cancel a pending approval request, ensuring that only relevant and timely actions move forward. Whether it's a shift in priorities or a simple mistake, this is your safety net for agile project management.

Request Body schema: application/json
required
reason
required
string

The reason for canceling the approval.

Responses

Request samples

Content type
application/json

An example showing a cancellation due to a change in project scope.

{
  • "reason": "Project scope changed, no longer needed."
}

Response samples

Content type
application/json
{
  • "id": "approval_12345",
  • "status": "canceled",
  • "cancelled_at": "2023-10-01T14:48:00.000Z",
  • "cancelled_by": "did:example:123456789abcdefghi",
  • "cancellation_reason": "Project scope changed, no longer needed."
}

Retrieve Approval Request Conversation History

Dive into the narrative of an approval request by accessing its conversation history. This endpoint serves to illuminate the decision-making process, showcasing interactions and deliberations that led to an approval. It supports both delegation and signed token authentication, ensuring secure access to sensitive dialogues.

Responses

Response samples

Content type
application/json
{
  • "approval_id": "12345",
  • "messages": [
    ]
}

Send a Message in Approval Conversation

In the intricate ballet of task approvals, communication is key. This endpoint lets you send a message within an approval conversation, fostering collaboration and ensuring clarity. If the conversation doesn't exist yet, fear not—it gracefully creates one, ensuring no message goes unheard.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Respond to an escalation request

In the dynamic world of Human-AI orchestration, escalations can arise requiring human oversight. This endpoint allows authorized users to respond to such escalations, fostering a collaborative decision-making process between humans and AI, ensuring transparency and accountability in task management.

Request Body schema: application/json
required
decision
required
string
Enum: "approved" "approved_with_modifications" "rejected" "request_changes" "delegated" "overridden"

The decision on the escalation

comment
string

Optional comment explaining the decision

modified_params
object

Optional parameters modified during decision

Responses

Request samples

Content type
application/json

An example of approving an escalation with a comment

{
  • "decision": "approved",
  • "comment": "Approved after reviewing the details",
  • "modified_params": { }
}

Response samples

Content type
application/json
null

Task Management

Retrieve pending approval requests

Navigate the intricate web of task approvals with this endpoint, designed to orchestrate queries across the HUMAN platform. Whether you're an approver, requester, or an automated task agent, this endpoint provides a streamlined view of approval requests, ensuring transparency and traceability in task management.

Responses

Response samples

Content type
application/json

Example of a successful response with multiple approval requests

{
  • "data": [
    ],
  • "limit": 10,
  • "next_cursor": "cursor_67890"
}

Retrieve detailed approval request information

Dive into the details of a specific approval request, uncovering the journey and decisions it entails. This endpoint enables tracking and understanding of task approval processes, ensuring transparency and accountability within the HUMAN platform.

Responses

Response samples

Content type
application/json

An organization 'acme' is reviewing an approval request for task routing.

{
  • "id": "approval_12345",
  • "task_id": "task_67890",
  • "agent_id": "agent_001",
  • "requester_passport_id": "passport_abc123",
  • "approver_passport_id": "passport_xyz789",
  • "action_description": "Request to approve invoice processing",
  • "risk_level": "medium",
  • "risk_factors": [
    ],
  • "alternatives": [
    ],
  • "request_data": {
    },
  • "escalation_schema": {
    },
  • "status": "pending",
  • "response": null,
  • "response_comment": null,
  • "responded_at": null,
  • "responded_by": null,
  • "modified_params": null,
  • "delegated_to": null,
  • "override_action": null,
  • "conversation_id": "conv_7890",
  • "created_at": "2023-10-01T10:00:00Z",
  • "expires_at": "2023-10-15T10:00:00Z",
  • "updated_at": "2023-10-01T10:05:00Z",
  • "provenance_id": "prov_123456"
}

Retrieve list of async task executions

Explore the universe of asynchronous task executions with this endpoint. It provides a rich view into ongoing and past tasks, empowering you to manage and track operations efficiently. Whether you're ensuring invoice processing completion or tracking AI model training, this endpoint is your window into the orchestration magic.

Responses

Response samples

Content type
application/json

Retrieve a list of async executions for 'acme' organization invoice processing tasks.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "queued_at"
}

Batch Create Tasks for Organization

Efficiently initiate multiple tasks within an organization at once, saving time and effort. This endpoint is a crucial tool for companies seeking to optimize task management at scale, ensuring all tasks are properly prioritized and tracked.

Request Body schema: application/json
required
required
Array of objects
object

Responses

Request samples

Content type
application/json

An example showing task creation with priority and callback URL.

{
  • "tasks": [
    ],
  • "batch_options": {}
}

Response samples

Content type
application/json
{
  • "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
  • "task_ids": [
    ]
}

Retrieve task status in workforce management

Discover the current status of a task within the workforce management system. This endpoint helps organizations monitor ongoing tasks, ensuring timely completion and efficient resource allocation by providing detailed insights into each task's lifecycle.

Responses

Response samples

Content type
application/json
{
  • "task_id": "task-12345",
  • "status": "in-progress",
  • "assigned_worker": "worker-6789",
  • "completed_at": null
}

Submit task review results

In the world of AI-human collaboration, every task completed deserves a review. This endpoint empowers you to submit your verdict on a task's outcome, ensuring quality and fostering continuous improvement in shared workflows.

Request Body schema: application/json
required
approved
required
boolean

Indicates if the task result is approved.

quality_score
number [ 0 .. 100 ]

A score reflecting the quality of the completed task.

feedback
string

Optional feedback on the task result.

corrections
string

Details of any corrections needed.

Responses

Request samples

Content type
application/json

Submitting a positive review with high quality score.

{
  • "approved": true,
  • "quality_score": 95,
  • "feedback": "Exceptional work, no corrections needed."
}

Response samples

Content type
application/json
null

Claim next task from workforce queue

This endpoint empowers a registered worker to claim the oldest eligible task from their organization's designated queue. Utilizing a safe, concurrent mechanism, it ensures tasks are claimed exactly once, preventing overlaps and ensuring integrity in task assignment.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json

A worker with a valid Passport DID claims a task.

{
  • "delegation": {
    }
}

Response samples

Content type
application/json
{
  • "taskId": "task789",
  • "taskDetails": {
    }
}

Retrieve work items for an organization

Dive into the heart of your organization's operations by exploring a curated list of work items. This endpoint empowers you to filter tasks based on status, urgency, and routing, ensuring you're always on top of what matters most. It's designed to help you manage tasks with precision, ensuring that nothing slips through the cracks.

Responses

Response samples

Content type
application/json

A response showing a paginated list of work items, with filtering applied.

{
  • "data": [
    ],
  • "next_cursor": "eyJjcmVhdGVkX2F0IjogIjIwMjMtMTAtMDJUMTQ6MzA6MDBaIiwgIndvcmtfaXRlbV9pZCI6ICJ3aTEyMzQ1In0="
}

Create a new workforce work item

This endpoint orchestrates the creation of a new work item within the HUMAN platform's workforce module. It enables organizations to delegate tasks efficiently while ensuring compliance through cryptographic identity verification and capability tracking. Whether you're routing tasks to a personal agent or a team, this endpoint ensures the task is correctly assigned and tracked.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Execute actions on workforce work items

This endpoint is a cornerstone of dynamic collaboration, enabling authorized agents to execute specific actions on work items in the HUMAN platform. By orchestrating tasks, it ensures that work items are processed efficiently and securely, aligning with organizational needs.

Request Body schema: application/json
required
action_id
required
string

The identifier for the action to be executed.

note
string

An optional note detailing the action.

revised_content
string

Revised content for edit actions.

form_data
object

Additional data for form-driven actions.

org_did
required
string

The decentralized identifier of the organization.

Responses

Request samples

Content type
application/json

An agent from 'acme' organization marking a task as 'approved' with additional notes.

{
  • "action_id": "approve",
  • "note": "Reviewed and approved by manager",
  • "org_did": "did:org:acme123"
}

Response samples

Content type
application/json
{
  • "id": "workitem123",
  • "status": "in_progress",
  • "actions_taken": [
    ]
}

Create a new Builder workflow

Embark on a journey to orchestrate tasks with ease by creating a new Builder workflow. This endpoint empowers organizations to define and manage workflows, streamlining operations and enhancing productivity. Whether you're just starting with a draft or deploying a full-fledged workflow, this endpoint is your gateway to efficient task orchestration.

Request Body schema: application/json
required
name
string

The display name of the workflow. Defaults to 'Untitled workflow'.

scope
string
Enum: "personal" "workspace" "org"

Defines the visibility scope of the workflow. Defaults to 'workspace'.

manifest
object

A detailed JSON object representing the workflow's structure.

lifecycle_state
string

The current lifecycle state of the workflow, e.g., 'draft'. Defaults to 'draft'.

Responses

Request samples

Content type
application/json

This example demonstrates creating a draft workflow with default settings.

{
  • "name": "Invoice Processing",
  • "scope": "workspace",
  • "manifest": {
    },
  • "lifecycle_state": "draft"
}

Response samples

Content type
application/json
{
  • "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "org_id": "org-1a2b3c",
  • "owner_did": "did:human:123456789abcdefghi",
  • "name": "Invoice Processing",
  • "scope": "workspace",
  • "lifecycle_state": "draft",
  • "manifest": {
    },
  • "version": 1,
  • "builder_flags": { },
  • "published_at": null,
  • "activated_at": null,
  • "created_at": "2023-10-10T14:48:00Z",
  • "updated_at": "2023-10-10T14:48:00Z"
}

Batch Query Capabilities for Tasks

Unlock the potential of your enterprise by efficiently querying capabilities across multiple tasks. This endpoint orchestrates a seamless interaction between human and AI capabilities, ensuring the right skills are matched to each task. It empowers organizations to harness their full potential by dynamically leveraging a distributed ledger of skills.

Request Body schema: application/json
required
org_id
required
string

Unique identifier for the organization.

required
Array of objects

Array of tasks with required capabilities.

object

Responses

Request samples

Content type
application/json

A query for Acme Corp to find capabilities for tasks.

{
  • "org_id": "acme-corp",
  • "queries": [
    ],
  • "options": {
    }
}

Response samples

Content type
application/json
null

HumanAIOrchestration

Respond to an approval request

In the ever-evolving landscape of human-AI collaboration, responding to approval requests ensures that tasks flow seamlessly between agents and AI. This endpoint empowers users to make pivotal decisions—approving, rejecting, or delegating—thereby maintaining the dynamic equilibrium of the HUMAN Protocol.

Request Body schema: application/json
required
decision
required
string
Enum: "approved" "approved_with_modifications" "rejected" "delegated" "overridden"

The decision made on the approval request.

comment
string

Optional comment providing additional context for the decision.

modified_params
object

Parameters modified during approval.

delegate_to
string

DID of the agent to whom the task is delegated, if applicable.

override_action
string

Action to override current settings, if necessary.

Responses

Request samples

Content type
application/json

Approving a request with a comment and modifications.

{
  • "decision": "approved_with_modifications",
  • "comment": "Approved with minor parameter updates",
  • "modified_params": {
    }
}

Response samples

Content type
application/json
null

Retrieve Capability Explanation

This endpoint unveils the hidden potential within a specific capability by providing a detailed explanation. It's the key to understanding how a capability ties into an individual's skill set, enabling more strategic task routing and efficient skill utilization within the HUMAN platform.

Responses

Response samples

Content type
application/json

An explanation for the capability associated with a specific Passport.

{
  • "capabilityId": "capability://12345",
  • "explanation": {
    },
  • "linkedSkills": [
    ]
}

WorkflowManagement

Cancel a Pending Approval Request

In the dynamic world of approval workflows, sometimes decisions change. This endpoint empowers users to cancel a pending approval request, ensuring that only relevant and timely actions move forward. Whether it's a shift in priorities or a simple mistake, this is your safety net for agile project management.

Request Body schema: application/json
required
reason
required
string

The reason for canceling the approval.

Responses

Request samples

Content type
application/json

An example showing a cancellation due to a change in project scope.

{
  • "reason": "Project scope changed, no longer needed."
}

Response samples

Content type
application/json
{
  • "id": "approval_12345",
  • "status": "canceled",
  • "cancelled_at": "2023-10-01T14:48:00.000Z",
  • "cancelled_by": "did:example:123456789abcdefghi",
  • "cancellation_reason": "Project scope changed, no longer needed."
}

Async Operations

Retrieve list of async task executions

Explore the universe of asynchronous task executions with this endpoint. It provides a rich view into ongoing and past tasks, empowering you to manage and track operations efficiently. Whether you're ensuring invoice processing completion or tracking AI model training, this endpoint is your window into the orchestration magic.

Responses

Response samples

Content type
application/json

Retrieve a list of async executions for 'acme' organization invoice processing tasks.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "queued_at"
}

AsyncExecution

Retrieve Async Execution Status

Uncover the current status and intricate details of an asynchronous execution task. This endpoint empowers users by providing not just the status, but a comprehensive view into the job's lifecycle and its journey through the HumanOS system. It's designed for those who need insights into task progress and execution outcomes in a distributed environment.

Responses

Response samples

Content type
application/json

Retrieve detailed status of an async execution for a task.

{
  • "id": "exec_12345",
  • "task_id": "task_67890",
  • "agent_id": "agent_alpha",
  • "requester_passport_id": "passport_abc123",
  • "job_id": "job_54321",
  • "queue_name": "mainQueue",
  • "priority": 5,
  • "status": "completed",
  • "result": {
    },
  • "error": null,
  • "progress_percent": 100,
  • "progress_message": "Execution completed successfully.",
  • "callback_url": "https://example.com/callback",
  • "callback_success": true,
  • "callback_attempts": 1,
  • "max_attempts": 3,
  • "current_attempt": 1,
  • "queued_at": "2023-10-21T10:20:30Z",
  • "started_at": "2023-10-21T10:30:00Z",
  • "completed_at": "2023-10-21T11:00:00Z",
  • "paused_at": null,
  • "paused_by": null,
  • "pause_reason": null,
  • "resume_count": 0,
  • "processing_pause_requested_at": null,
  • "provenance_id": "prov_334455",
  • "run_state": "finalized",
  • "current_step": "summary"
}

AsyncExecutions

Cancel a queued async execution

In the dynamic world of Human-AI orchestration, speed and precision are vital. This endpoint allows you to cancel an async execution that is queued, providing agility in task management. Use it when priorities shift or tasks are no longer valid, ensuring optimal resource allocation.

Responses

Response samples

Content type
application/json

A successful cancellation of an async execution

{
  • "id": "execution_12345",
  • "status": "cancelled",
  • "completed_at": "2023-10-05T14:48:00.000Z"
}

Pause asynchronous execution by ID

In the dynamic world of task management, sometimes processes need a pause. This endpoint allows you to pause a specified asynchronous execution, offering a respite for the system to handle priorities or address issues. Leveraging the HUMAN Protocol's cryptographic identity (Passport), this operation ensures secure and authorized task handling.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Resume an asynchronous execution

In the dynamic world of AI-driven operations, tasks sometimes pause for various reasons. This endpoint lets authorized agents resume a paused asynchronous execution, ensuring that workflows can continue without missing a beat. By leveraging cryptographic identities and delegations, it securely manages task resumption.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json

An example showing the URL with execution ID and necessary headers.

{
  • "headers": {
    },
  • "url": "/v1/async-executions/12345/resume"
}

Response samples

Content type
application/json

The response after successfully resuming an execution.

{
  • "id": "12345",
  • "status": "running",
  • "job_id": "job_67890",
  • "resume_count": 2,
  • "queued_at": "2023-10-05T14:48:00.000Z"
}

TaskManagement

Cancel a queued async execution

In the dynamic world of Human-AI orchestration, speed and precision are vital. This endpoint allows you to cancel an async execution that is queued, providing agility in task management. Use it when priorities shift or tasks are no longer valid, ensuring optimal resource allocation.

Responses

Response samples

Content type
application/json

A successful cancellation of an async execution

{
  • "id": "execution_12345",
  • "status": "cancelled",
  • "completed_at": "2023-10-05T14:48:00.000Z"
}

Retrieve HumanOS Task Captures

Unlock insights into task orchestration by fetching a list of captures associated with your organization's decentralized identity. This endpoint empowers organizations to track provenance and understand task flows through the HUMAN platform.

Responses

Response samples

Content type
application/json

An organization retrieves a paginated list of task captures for analysis.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Retrieve detailed work item information

Unlock the intricate details of a specific work item within the HUMAN ecosystem. This endpoint enables organizations to track and manage workforce tasks with precision, ensuring each task aligns with their strategic goals and operational needs.

Responses

Response samples

Content type
application/json

Details of a work item processed by Acme Corp

{
  • "id": "wi-123456",
  • "org_did": "did:human:acme",
  • "installation_id": "inst-001",
  • "renderer_id": "renderer-007",
  • "artifact_id": "artifact-789",
  • "status": "in_progress",
  • "routed_to_type": "agent",
  • "routed_to_id": "agent-42",
  • "routed_by": "agent-5",
  • "urgency": "high",
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-02T15:30:00Z",
  • "completed_at": null,
  • "actions_taken": "Reviewed documentation, initiated process",
  • "feedback_emitted": "Positive feedback"
}

Pause asynchronous execution by ID

In the dynamic world of task management, sometimes processes need a pause. This endpoint allows you to pause a specified asynchronous execution, offering a respite for the system to handle priorities or address issues. Leveraging the HUMAN Protocol's cryptographic identity (Passport), this operation ensures secure and authorized task handling.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Resume an asynchronous execution

In the dynamic world of AI-driven operations, tasks sometimes pause for various reasons. This endpoint lets authorized agents resume a paused asynchronous execution, ensuring that workflows can continue without missing a beat. By leveraging cryptographic identities and delegations, it securely manages task resumption.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json

An example showing the URL with execution ID and necessary headers.

{
  • "headers": {
    },
  • "url": "/v1/async-executions/12345/resume"
}

Response samples

Content type
application/json

The response after successfully resuming an execution.

{
  • "id": "12345",
  • "status": "running",
  • "job_id": "job_67890",
  • "resume_count": 2,
  • "queued_at": "2023-10-05T14:48:00.000Z"
}

Visualization

Retrieve Workflow DAG Visual Representation

Uncover the intricate dance of tasks with a detailed Directed Acyclic Graph (DAG) for a specified workflow. This endpoint empowers users to visualize workflow orchestration, aiding in understanding complex task dependencies and execution flows.

Responses

Response samples

Content type
application/json
{
  • "workflow_id": "workflow-123",
  • "nodes": [
    ],
  • "edges": [
    ],
  • "stats": {
    }
}

Statistics

Retrieve workflow execution statistics

Unlock insights into your workflows with detailed statistics. This endpoint is your gateway to understanding execution patterns, helping you optimize for efficiency and reliability. Discover the story behind every node in your workflow.

Responses

Response samples

Content type
application/json

Statistics for Acme Corporation's invoice processing workflow.

{
  • "workflow_id": "wf-12345",
  • "total_runs": 150,
  • "completed": 145,
  • "failed": 5,
  • "avg_duration_ms": 200,
  • "p99_duration_ms": 350
}

Status

Retrieve the status of a delegation

In the realm of Human-AI orchestration, understanding the status of a delegation is crucial for seamless task execution. This endpoint allows you to verify whether a delegation is active, revoked, or expired, ensuring optimal alignment between human and AI capabilities. It exists to safeguard against unauthorized actions and maintain integrity within the HUMAN ecosystem.

Responses

Response samples

Content type
application/json
Example

A delegation that is currently active.

{
  • "delegation_id": "d1234",
  • "status": "active"
}

Discover the HUMAN API's live status

This root discovery endpoint is your gateway to the HUMAN API, offering real-time insights into its operational status. It serves as the heartbeat of the HUMAN platform, ensuring that the trust layer between human decisions and machine execution remains robust and transparent.

Responses

Response samples

Content type
application/json

An example where the HUMAN API is fully operational.

{}

Education

Retrieve curated list of academy courses

Embark on a journey to expand your knowledge with our academy's diverse course offerings. This endpoint provides a curated list of courses, complete with filtering options for category and difficulty, empowering users to tailor their learning path to their interests and skill level.

Responses

Response samples

Content type
application/json

Returning a list of courses filtered by category 'Technology'.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at",
  • "hasMore": false
}

Update Learner's Academic Progress

Track learners' journey through your educational content with precision. This endpoint empowers educators by recording progress metrics, enabling tailored learning paths and ensuring every student reaches their full potential.

Request Body schema: application/json
required
enrollment_id
required
string

Unique identifier for the learner's enrollment.

overall_progress
required
integer

Progress percentage, must be an integer between 0 and 100.

lesson_id
string

Identifier of the last lesson accessed by the learner.

completed
boolean

Indicates if the last lesson was completed.

time_spent_seconds
integer

Time spent on the last lesson in seconds.

interactions
object

Additional data regarding learner interactions during the lesson.

Responses

Request samples

Content type
application/json

This example illustrates a progress update for a learner who completed the lesson with some interaction data.

{
  • "enrollment_id": "enroll_12345",
  • "overall_progress": 75,
  • "lesson_id": "lesson_6789",
  • "completed": true,
  • "time_spent_seconds": 3600,
  • "interactions": {
    }
}

Response samples

Content type
application/json
{
  • "progress_id": "prog_rec_98765",
  • "enrollment_id": "enroll_12345",
  • "lesson_id": "lesson_6789",
  • "completed": true,
  • "recorded_at": "2023-10-08T14:53:00Z",
  • "overall_progress": 75,
  • "next_lesson": null
}

Courses

Retrieve curated list of academy courses

Embark on a journey to expand your knowledge with our academy's diverse course offerings. This endpoint provides a curated list of courses, complete with filtering options for category and difficulty, empowering users to tailor their learning path to their interests and skill level.

Responses

Response samples

Content type
application/json

Returning a list of courses filtered by category 'Technology'.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at",
  • "hasMore": false
}

Create a new course offering

In the ever-evolving landscape of learning, this endpoint empowers organizations to craft new educational journeys. By enabling the creation of courses, it fuels the continuous growth of human potential, orchestrated with precision by AI.

Request Body schema: application/json
required
title
required
string

The title of the course

description
string

A detailed description of the course

capability_ids
Array of strings

List of capability identifiers needed for the course

duration_minutes
integer >= 0

Duration of the course in minutes

difficulty
string
Enum: "beginner" "intermediate" "advanced"

The difficulty level of the course

is_published
boolean

Whether the course is published

category
string

The category under which the course falls

Responses

Request samples

Content type
application/json

This example demonstrates the creation of a beginner-level course on AI fundamentals.

{
  • "title": "AI Fundamentals",
  • "description": "An introductory course to artificial intelligence.",
  • "capability_ids": [
    ],
  • "duration_minutes": 120,
  • "difficulty": "beginner",
  • "is_published": true,
  • "category": "Technology"
}

Response samples

Content type
application/json
{
  • "course_id": "course-12345",
  • "title": "AI Fundamentals",
  • "description": "An introductory course to artificial intelligence.",
  • "capability_ids": [
    ],
  • "category": "Technology",
  • "duration_minutes": 120,
  • "difficulty": "beginner",
  • "is_published": true,
  • "created_at": "2023-10-01T12:00:00Z"
}

Retrieve detailed course information

Unlock the potential of learning by fetching detailed information about a specific course within the HUMAN academy. This endpoint allows you to delve into the intricacies of a course, from its skill capabilities to its duration and difficulty, empowering learners and educators to make informed decisions.

Responses

Response samples

Content type
application/json

Fetching the course details for 'AI Ethics 101'.

{
  • "course_id": "course_123",
  • "title": "AI Ethics 101",
  • "description": "An introductory course on ethical considerations in AI.",
  • "capability_ids": [
    ],
  • "category": "Ethics",
  • "duration_minutes": 90,
  • "difficulty": "Intermediate",
  • "is_published": true,
  • "created_at": "2023-01-15T13:45:30Z",
  • "updated_at": "2023-02-10T09:35:45Z"
}

Academy

Create a new course offering

In the ever-evolving landscape of learning, this endpoint empowers organizations to craft new educational journeys. By enabling the creation of courses, it fuels the continuous growth of human potential, orchestrated with precision by AI.

Request Body schema: application/json
required
title
required
string

The title of the course

description
string

A detailed description of the course

capability_ids
Array of strings

List of capability identifiers needed for the course

duration_minutes
integer >= 0

Duration of the course in minutes

difficulty
string
Enum: "beginner" "intermediate" "advanced"

The difficulty level of the course

is_published
boolean

Whether the course is published

category
string

The category under which the course falls

Responses

Request samples

Content type
application/json

This example demonstrates the creation of a beginner-level course on AI fundamentals.

{
  • "title": "AI Fundamentals",
  • "description": "An introductory course to artificial intelligence.",
  • "capability_ids": [
    ],
  • "duration_minutes": 120,
  • "difficulty": "beginner",
  • "is_published": true,
  • "category": "Technology"
}

Response samples

Content type
application/json
{
  • "course_id": "course-12345",
  • "title": "AI Fundamentals",
  • "description": "An introductory course to artificial intelligence.",
  • "capability_ids": [
    ],
  • "category": "Technology",
  • "duration_minutes": 120,
  • "difficulty": "beginner",
  • "is_published": true,
  • "created_at": "2023-10-01T12:00:00Z"
}

Retrieve detailed course information

Unlock the potential of learning by fetching detailed information about a specific course within the HUMAN academy. This endpoint allows you to delve into the intricacies of a course, from its skill capabilities to its duration and difficulty, empowering learners and educators to make informed decisions.

Responses

Response samples

Content type
application/json

Fetching the course details for 'AI Ethics 101'.

{
  • "course_id": "course_123",
  • "title": "AI Ethics 101",
  • "description": "An introductory course on ethical considerations in AI.",
  • "capability_ids": [
    ],
  • "category": "Ethics",
  • "duration_minutes": 90,
  • "difficulty": "Intermediate",
  • "is_published": true,
  • "created_at": "2023-01-15T13:45:30Z",
  • "updated_at": "2023-02-10T09:35:45Z"
}

Retrieve learner enrollments with filters

Dive into the world of learning by exploring enrollments filtered by status or learner. This endpoint empowers organizations to seamlessly track and manage educational journeys, ensuring learners are on the right path to success.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "enrolled_at",
  • "hasMore": false
}

Enroll Learner in Academy Course

Embark on a journey of knowledge with the HUMAN platform's Academy. This endpoint allows learners to enroll in courses, leveraging their digital identity. Whether you're a seasoned professional or a curious novice, track your progress and elevate your skills seamlessly.

Request Body schema: application/json
required
did
string

Decentralized Identifier for the learner.

learner_id
string

Unique identifier of the learner.

passport_id
string

Passport ID representing the learner's identity.

course_id
required
string

The course identifier in which the learner wishes to enroll.

Responses

Request samples

Content type
application/json

A learner enrolls using their Decentralized Identifier.

{
  • "did": "did:human:12345",
  • "course_id": "course-101"
}

Response samples

Content type
application/json
null

Complete an Enrollment and Anchor to Ledger

This endpoint finalizes a learner's enrollment by marking it as complete and issuing a cryptographic certification on the Distributed Ledger. This ensures an immutable proof of completion, paving the way for capability grants and further learning opportunities.

Responses

Response samples

Content type
application/json

Marks the enrollment as complete and returns the completion details.

{
  • "enrollment_id": "123e4567-e89b-12d3-a456-426614174000",
  • "status": "completed",
  • "completed_at": "2023-10-12T08:45:00Z"
}

Retrieve enrollment progress details

Unlock the journey of learning by delving into the progress of a specific enrollment. This endpoint provides a window into a learner's path within a course, offering insights into their current status, progress milestones, and activity history. It's a tool for educators to tailor support and for learners to reflect on their educational voyage.

Responses

Response samples

Content type
application/json

A learner enrolled in the 'Advanced Data Science' course showing significant progress.

{
  • "enrollment_id": "enroll123",
  • "course_id": "course456",
  • "course_title": "Advanced Data Science",
  • "overall_progress": 75,
  • "modules": [ ],
  • "next_lesson": "lesson789",
  • "total_time_spent_minutes": 1200,
  • "last_activity": "2023-10-05T14:48:00Z",
  • "on_track": true,
  • "status": "enrolled",
  • "enrolled_at": "2023-01-10T10:00:00Z",
  • "completed_at": null,
  • "progress_context": { }
}

Capture Skill Event with Builder Completion

This endpoint allows the HUMAN platform to record the completion of an AcademyMoment by a user, along with any associated skill signals. It enhances the platform's knowledge about a user's capabilities and progress, ensuring a more personalized and effective task routing experience.

Request Body schema: application/json
required
user_did
string

The decentralized identifier (DID) of the user. Optional if delegation is provided.

skill_id
required
string

The identifier for the skill being logged.

event_type
required
string

The type of event being recorded, such as 'completion' or 'initiation'.

context
object

Additional context about the event, provided as a key-value map.

Responses

Request samples

Content type
application/json

Logs a skill completion event for a user with a corresponding skill and context.

{
  • "user_did": "did:example:123456789abcdefghi",
  • "skill_id": "skill:acme:invoice-processing",
  • "event_type": "completion",
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "id": "evt_01F8ZK9Z4TJ1T9Y3V7Q4GV8G5D",
  • "occurred_at": "2023-10-15T14:50:00.000Z"
}

Analyze capability gaps for target roles

The gap analysis endpoint evaluates the Learning Capability Evidence Framework (LCEF) portfolio against a specified target role or capability. By understanding these gaps, organizations can tailor training to help individuals achieve their desired roles.

Responses

Response samples

Content type
application/json

Evaluates the gaps in a portfolio for transitioning to a Data Analyst role.

{
  • "target_role": "Data Analyst",
  • "gap_summary": {
    },
  • "next_best_proof": [
    ]
}

Workflow Management

Retrieve paginated list of workflows

Dive into the world of orchestrated tasks with our workflow listing endpoint. This API call reveals a curated collection of workflows, each a story of human and AI collaboration, allowing you to track progress, performance, and history. It's your window into the seamless dance of tasks performed by agents, perfect for audit trails and operational oversight.

Responses

Response samples

Content type
application/json

A snapshot of Acme Org's active workflows with status and metrics.

{
  • "data": [
    ],
  • "has_more": false
}

Pause a running workflow instance

In the realm of orchestrating complex tasks, sometimes workflows need a moment to pause and breathe. This endpoint empowers users to pause an active workflow, transitioning all running nodes to a state of waiting approval. It ensures that no step is taken without consideration, while logging the pause for transparency and accountability.

Responses

Response samples

Content type
application/json

An example illustrating a successful pause of a workflow with several running nodes.

{
  • "workflow_id": "workflow-12345",
  • "status": "paused",
  • "paused_nodes": 3,
  • "paused_at": "2023-10-05T14:48:00.000Z"
}

Trigger a workflow manually

Spark the lifeline of automation by manually triggering a workflow. This endpoint initiates a new Directed Acyclic Graph (DAG) root node and sends a beacon, the workflow.manual-trigger event, for Inngest to capture and act upon. It's designed for those moments when you need to intervene and start a process outside the regular flow, providing flexibility and control in orchestrating complex operations.

Request Body schema: application/json
required
context
object

Additional data to pass along with the workflow trigger

Responses

Request samples

Content type
application/json

Triggering a workflow with minimal context

{
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "workflow_id": "wf12345",
  • "run_id": "wrun67890",
  • "status": "triggered",
  • "triggered_at": "2023-10-11T14:32:08Z"
}

Delete a Builder Workflow by ID

In the dynamic world of workflow automation, maintaining a clean slate is crucial. This endpoint empowers organizations to remove obsolete or incorrect workflows, ensuring their operational landscape remains efficient and relevant. By providing this ability, we help teams focus on what matters most: innovation and productivity.

Responses

Response samples

Content type
application/json
null

Promote workflow scope within an organization

Elevate the scope of a workflow from a personal level to a broader organizational level, ensuring essential workflows gain the visibility they deserve. This endpoint empowers administrators to streamline operations by adjusting workflow accessibility and visibility across different levels of the organization.

Request Body schema: application/json
required
scope
required
string
Enum: "personal" "workspace" "org"

The target scope to promote the workflow to: personal, workspace, or org

Responses

Request samples

Content type
application/json

Illustrates changing a workflow's scope from personal to organizational level.

{
  • "scope": "org"
}

Response samples

Content type
application/json
{
  • "id": "wf123",
  • "scope": "org",
  • "updated_at": "2023-10-05T14:48:00Z"
}

Task Orchestration

Retrieve paginated list of workflows

Dive into the world of orchestrated tasks with our workflow listing endpoint. This API call reveals a curated collection of workflows, each a story of human and AI collaboration, allowing you to track progress, performance, and history. It's your window into the seamless dance of tasks performed by agents, perfect for audit trails and operational oversight.

Responses

Response samples

Content type
application/json

A snapshot of Acme Org's active workflows with status and metrics.

{
  • "data": [
    ],
  • "has_more": false
}

Pause a running workflow instance

In the realm of orchestrating complex tasks, sometimes workflows need a moment to pause and breathe. This endpoint empowers users to pause an active workflow, transitioning all running nodes to a state of waiting approval. It ensures that no step is taken without consideration, while logging the pause for transparency and accountability.

Responses

Response samples

Content type
application/json

An example illustrating a successful pause of a workflow with several running nodes.

{
  • "workflow_id": "workflow-12345",
  • "status": "paused",
  • "paused_nodes": 3,
  • "paused_at": "2023-10-05T14:48:00.000Z"
}

Marketplace

Discover and explore marketplace connectors

Dive into the vibrant ecosystem of HUMAN's marketplace where you can explore and filter public connectors. This endpoint empowers you to search by various parameters, discovering connectors that meet your specific needs and capabilities. It's designed to enhance your interaction with the HUMAN ecosystem by providing a curated list of AI tools and connectors.

Responses

Response samples

Content type
application/json

An example response showing a list of connectors from the marketplace, filtering by provider 'acme'.

{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "2"
}

Explore marketplace assets effortlessly

Venture into the HUMAN marketplace to discover a wide array of assets, curated for global visibility and approved for seamless integration. This endpoint empowers users to browse without authentication, ensuring open access to valuable resources while maintaining security for publisher-specific content.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "hasMore": false,
  • "cursor": "2023-10-01T12:00:00Z"
}

Submit asset for review in marketplace

Embark on a journey to elevate your asset to the marketplace stage by submitting it for a comprehensive review. This process ensures that the asset meets all standards and is ready to make an impact. Replacing the direct publish method, this submission sets the foundation for meticulous vetting, transforming your asset into a beacon of quality.

Request Body schema: application/json
required
name
required
string

The name of the asset.

asset_type
required
string

The type of asset being submitted, such as extension or bundle.

manifest_json
required
object

The manifest detailing the asset's specifications and requirements.

object

Additional metadata for the asset.

visibility
string

The visibility level of the asset, e.g., org_private.

lifecycle_stage
string

The current lifecycle stage of the asset, e.g., production.

Responses

Request samples

Content type
application/json

Submitting an extension asset for review.

{
  • "name": "AcmeExtension",
  • "asset_type": "extension",
  • "manifest_json": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
null

Retrieve Agent Templates from Marketplace

Uncover the treasure trove of agent templates available in the HUMAN marketplace. This endpoint empowers you to explore a collection of predefined task orchestrations, essential for any organization looking to optimize human-AI collaboration swiftly.

Responses

Response samples

Content type
application/json

Fetching the first page of templates for organization 'acme'.

{
  • "data": [
    ],
  • "limit": 2,
  • "cursor": "opaque-cursor-string",
  • "hasMore": true
}

Retrieve Installed Marketplace Assets

In the bustling ecosystem of HUMAN, knowing what assets your organization has harnessed is crucial. This endpoint unveils the list of marketplace assets currently powering an organization, offering insights into the tools and capabilities actively in play. By maintaining a current view of installed assets, organizations can ensure alignment with their strategic goals and optimize their operational efficiency.

Responses

Response samples

Content type
application/json

Shows a list of installed assets for an organization.

{
  • "data": [
    ]
}

Retrieve a marketplace asset by ID

Dive into the dynamic world of HUMAN's marketplace by exploring a specific asset through its unique identifier. This endpoint not only unveils the asset's details but also provides a glimpse into its latest user feedback, fostering an informed decision-making process.

Responses

Response samples

Content type
application/json
{
  • "id": "asset-12345",
  • "name": "AI Invoice Processor",
  • "description": "An AI tool that automates invoice processing for enterprises.",
  • "latest_review": {
    }
}

Fetch reviews for a marketplace asset

Discover the insights and feedback from users for a specific asset on the Developer Home page. This endpoint exists to provide transparency and assist developers in improving their offerings by learning from user experiences.

Responses

Response samples

Content type
application/json

A list of reviews for the asset with ID 'asset123'.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursor": null,
  • "hasMore": false
}

Install Marketplace Asset to Organization

Seamlessly integrate pre-approved marketplace assets into your organization using the HUMAN platform. This endpoint facilitates the installation process by ensuring assets meet organizational policies and trust tiers, empowering organizations to expand their capabilities securely.

Request Body schema: application/json
required
asset_id
required
string

Unique identifier for the asset to be installed.

org_did
required
string

Decentralized identifier (DID) of the organization.

object

Configuration overrides specific to the asset installation.

preset
string
Default: "safe"

Preset configuration for the asset, defaults to 'safe'.

custom_scopes
Array of strings

Custom scopes required for asset installation.

Responses

Request samples

Content type
application/json

Install a simple extension asset to an organization.

{
  • "asset_id": "asset-12345",
  • "org_did": "did:org:acme",
  • "config_overrides": { },
  • "preset": "safe"
}

Response samples

Content type
application/json
{
  • "result": "Asset 'asset-12345' successfully installed for organization 'did:org:acme'."
}

Uninstall asset with delegation revocation

Uninstall a marketplace asset, cascading the removal of associated delegations. This endpoint is vital for maintaining clean operational environments by ensuring that unused assets do not retain lingering permissions, thus upholding security and efficiency.

Request Body schema: application/json
required
asset_id
required
string

The unique identifier of the asset to be uninstalled.

org_did
required
string

The decentralized identifier for the organization.

Responses

Request samples

Content type
application/json

Uninstall an asset from the 'acme' organization.

{
  • "asset_id": "asset_12345",
  • "org_did": "did:example:acme"
}

Response samples

Content type
application/json
{
  • "uninstalled": true,
  • "installation": {
    }
}

Retrieve pending marketplace asset reviews

In the vibrant ecosystem of the HUMAN platform, the review queue serves as a crucial checkpoint for marketplace assets awaiting human scrutiny. This endpoint invites administrators to survey the pending and escalated items, ensuring that each asset aligns with the platform's standards and values. By scrutinizing these assets, administrators uphold the integrity and safety that HUMAN users rely upon.

Responses

Response samples

Content type
application/json

An example showing a list of assets from Acme Corp awaiting review.

{
  • "data": [
    ],
  • "hasMore": true,
  • "cursor": "eyJjcmVhdGVkX2F0IjoiMjAyMy0wOS0zMFQxMTozMzo1NVoiLCJpZCI6ImFzc2V0LTEyMyJ9"
}

Decide on Asset Review Outcome

Empower human reviewers to influence the marketplace by approving, rejecting, or requesting changes to assets. This decision-making endpoint is pivotal in ensuring asset quality and compliance, particularly when AI alone cannot guarantee safety or fairness.

Request Body schema: application/json
required
decision
required
string
Enum: "approve" "reject" "request_changes"

The decision made by the reviewer.

bypass_compute_billing_gate
boolean

Flag to bypass the compute billing gate, requires admin scope.

bypass_iframe_trust_gate
boolean

Flag to bypass the iframe trust gate, requires admin scope.

notes
string

Additional notes from the reviewer about the decision.

risk_assessment
object

Optional JSON object for any risk assessments conducted.

Responses

Request samples

Content type
application/json

Approving an agent asset with a valid cost profile.

{
  • "decision": "approve",
  • "notes": "The asset meets all criteria and is ready for approval.",
  • "risk_assessment": {
    }
}

Response samples

Content type
application/json
null

Elevate an asset's trust tier

Promote the trust tier of a marketplace asset to enhance its credibility and unlock new capabilities. This operation is critical for assets aspiring to reach higher levels of trust and visibility, reflecting their reliability and adherence to safety standards.

Request Body schema: application/json
required
trust_tier
required
string
Enum: "community" "verified" "certified" "enterprise"

The trust level to promote the asset to

Responses

Request samples

Content type
application/json

Example of promoting an asset to the 'enterprise' trust tier.

{
  • "trust_tier": "enterprise"
}

Response samples

Content type
application/json

The asset was successfully promoted to the 'enterprise' tier.

{
  • "id": "asset-12345",
  • "trust_tier": "enterprise"
}

Promote asset lifecycle stage within marketplace

Elevate the lifecycle stage of a marketplace asset, ensuring it meets the necessary criteria for progression. This endpoint is crucial for managing asset readiness and compliance in a structured, verifiable manner.

Request Body schema: application/json
required
to
required
string
Enum: "staging" "production"

The desired lifecycle stage to promote the asset to.

Responses

Request samples

Content type
application/json

Promoting an asset from staging to production.

{
  • "to": "production"
}

Response samples

Content type
application/json
{
  • "id": "asset-123",
  • "lifecycle_stage": "production",
  • "publisher_id": "org-789",
  • "updated_at": "2023-10-15T12:45:30Z"
}

Rollback asset lifecycle stage

Navigate the complex journey of digital assets within HUMAN's marketplace by rolling back their lifecycle stage. This endpoint empowers you to manage asset transitions with precision, ensuring the continuity and safety of AI-orchestrated tasks.

Request Body schema: application/json
required
to
required
string
Enum: "staging" "development" "production"

The desired stage to rollback to (e.g., 'staging').

Responses

Request samples

Content type
application/json

This example rolls back the asset lifecycle stage to 'staging'.

{
  • "to": "staging"
}

Response samples

Content type
application/json
null

Retrieve analytics for a marketplace asset

Dive into the heart of your asset's performance with this endpoint. Designed for publishers and administrators, it surfaces valuable metrics like installations, usage, and pseudo-revenue. Understanding these analytics helps you optimize your asset's presence in the marketplace, driving strategic decisions and growth.

Responses

Response samples

Content type
application/json

An example showing analytics for an asset over a 30-day period.

{
  • "asset_id": "asset123",
  • "asset_name": "AI Invoice Processor",
  • "asset_type": "application",
  • "trust_tier": "high",
  • "period": {
    },
  • "installs": {
    },
  • "usage": {
    },
  • "revenue": {
    },
  • "top_orgs_by_usage": [
    ]
}

Synchronize Marketplace Assets

In the vast ecosystem of human and AI collaboration, staying updated is crucial. This endpoint allows self-hosted platforms to synchronize with the latest approved and globally visible assets from haio.run. By leveraging this, organizations can ensure they have the most current tools and resources at their disposal, enhancing their capability graph and ensuring seamless operations.

Responses

Response samples

Content type
application/json

The response includes a list of assets that have been updated since the last sync.

{
  • "assets": [
    ],
  • "synced_at": "2023-10-07T14:35:00Z"
}

Retrieve detailed connector information

Dive into the rich details of any public connector available on the HUMAN marketplace. This endpoint allows you to explore the capabilities and statistics of connectors, empowering informed decisions about integration and usage.

Responses

Response samples

Content type
application/json
{
  • "connector_id": "b7d2e9f1",
  • "name": "Invoice Processor",
  • "provider": "Acme Corp",
  • "description": "Automates invoice processing tasks",
  • "long_description": "The Invoice Processor streamlines the handling of invoices by leveraging AI to ensure accuracy and speed.",
  • "icon_url": "https://example.com/icons/invoice-processor.png",
  • "version": "1.4.2",
  • "publisher": {
    },
  • "certified": true,
  • "pricing_model": "subscription",
  • "capabilities": [
    ],
  • "oauth": {},
  • "deployment_modes": [
    ],
  • "configuration_schema": {
    },
  • "health_status": "healthy",
  • "last_health_check_at": "2023-10-01T12:00:00Z",
  • "statistics": {
    },
  • "created_at": "2022-06-15T08:30:00Z",
  • "updated_at": "2023-09-10T14:45:00Z"
}

Install a Connector for Organization

In the HUMAN ecosystem, connectors are bridges that allow organizations to integrate external services seamlessly. This endpoint empowers your organization to install a connector, ensuring a smooth flow of operations across platforms. The installation process is authenticated via a Passport delegation token, safeguarding your organization's integrity.

Request Body schema: application/json
required
deployment_mode
required
string
Enum: "cloud" "hybrid" "self-hosted"

The mode in which the connector will be deployed.

granted_permissions
required
Array of strings

A list of permissions the connector is granted upon installation.

object

Optional configuration settings specific to the connector.

Responses

Request samples

Content type
application/json

This example demonstrates installing a connector with cloud deployment mode and specific permissions.

{
  • "deployment_mode": "cloud",
  • "granted_permissions": [
    ],
  • "config": {}
}

Response samples

Content type
application/json
Example

An example response when a connector is installed and active.

{
  • "installation_id": "install_123456",
  • "connector_id": "connector_7890",
  • "status": "active",
  • "installed_at": "2023-10-15T12:00:00Z"
}

Uninstall a marketplace connector

This endpoint allows you to seamlessly remove a connector from your organization's ecosystem, ensuring that only relevant tools remain active. By managing your connectors effectively, you maintain a streamlined and secure operational environment, fostering both innovation and governance.

Request Body schema: application/json
required
entity_id
string

The unique identifier of the entity within the organization.

Responses

Request samples

Content type
application/json

Uninstalls a connector for the 'acme' organization.

{
  • "entity_id": "acme-organization-123"
}

Response samples

Content type
application/json
null

Publish a connector to the marketplace

In the HUMAN ecosystem, publishing a connector is more than just uploading code—it's about establishing a trusted identity and sharing innovations with the world. This endpoint allows verified developers to publish their connectors, ensuring that their creations carry their identity and reputation across the HUMAN network. With a focus on integrity and security, published connectors must meet identity verification standards, ensuring that every contribution is backed by a real person.

Request Body schema: application/json
required
connector_id
string

Unique identifier for the connector

name
required
string

Human-readable name of the connector

description
string

Detailed description of the connector's functionality

version
required
string

Semantic version of the connector

object

Connector manifest details

handles_sensitive_data
boolean

Indicates if the connector handles sensitive data

pricing_model
string
Enum: "free" "paid" "freemium"

The pricing model for the connector

deployment_modes
Array of strings
Items Enum: "cloud" "hybrid" "self-hosted"

Supported deployment modes

Responses

Request samples

Content type
application/json

Publishing a simple connector with a free pricing model and cloud deployment.

{
  • "name": "acme-invoice-processor",
  • "version": "1.0.0",
  • "description": "Processes invoices for the Acme organization",
  • "manifest": {
    },
  • "pricing_model": "free",
  • "deployment_modes": [
    ]
}

Response samples

Content type
application/json
{
  • "publish_id": "pub-123456",
  • "status": "published",
  • "publisher_did": "did:human:1234abcd",
  • "connector_id": "acme-invoice-processor",
  • "name": "Acme Invoice Processor",
  • "version": "1.0.0",
  • "message": "You're verified. Your published work carries your identity — it's your reputation, portable and permanent.",
  • "created_at": "2023-10-12T07:20:50.52Z"
}

Retrieve the Natural Gate Map

In your journey through the HUMAN ecosystem, understanding the access gates is crucial. This endpoint unveils the natural gate map, illustrating which capabilities demand specific verification levels. It's designed to empower frontends with the intelligence to guide users smoothly through their tasks, ensuring they are prepared before encountering a gate.

Responses

Response samples

Content type
application/json

A snapshot of various gates including actions and their requirements.

{
  • "gates": [
    ]
}

Automate Marketplace Review Process

Embark on a journey to ensure your marketplace listings meet HUMAN platform standards through automated checks. This endpoint not only verifies your agent's installation manifest but also assesses eligibility for the prestigious Autonomous badge. This pre-submission tool is your ally in maintaining high-quality entries.

Request Body schema: application/json
required
agent_id
required
string

Unique identifier for the agent

required
object

Agent's installation manifest

openapi_spec
object

OpenAPI specification for the agent

request_badge
boolean

Flag to request Autonomous badge check

Responses

Request samples

Content type
application/json

Reviewing a standard agent's manifest with a request for an Autonomous badge.

{
  • "agent_id": "agent_12345",
  • "manifest": {
    },
  • "openapi_spec": {
    },
  • "request_badge": true
}

Response samples

Content type
application/json
{
  • "review": {
    },
  • "badge": {
    }
}

Submit a new marketplace listing

The marketplace submission endpoint is your gateway to showcasing your AI's capabilities to the world. Here, you validate your submission, undergo a rigorous automated review, and, if successful, enter the submission queue. This ensures only the best and most compliant agents make it to the HUMAN platform.

Request Body schema: application/json
required
agent_id
required
string

A unique identifier for the submitting agent.

publisher_did
required
string

The decentralized identifier (DID) of the publisher.

manifest
required
object

The detailed manifest of the agent, conforming to the InstallManifest schema.

openapi_spec
object

An optional OpenAPI specification for the agent.

Responses

Request samples

Content type
application/json

A submission by Acme Corp for their invoice processing AI agent.

{
  • "agent_id": "acme-invoice-processor",
  • "publisher_did": "did:example:acme123",
  • "manifest": {
    },
  • "openapi_spec": {
    }
}

Response samples

Content type
application/json
null

Submit a rating for a marketplace connector

In the vibrant ecosystem of HUMAN's marketplace, connectors are the lifeblood that enable seamless integration. This endpoint empowers users to express their satisfaction or critique by rating connectors they have installed. A rating not only influences the connector's reputation but also guides future users in their decision-making process.

Request Body schema: application/json
required
rating
required
integer [ 1 .. 5 ]

The rating score given to the connector, must be between 1 and 5.

installation_id
required
string

The unique identifier of the connector installation being rated.

review_text
string

An optional textual review providing more context about the rating.

Responses

Request samples

Content type
application/json

A rating example where Acme Corp rates a connector they use for invoice processing.

{
  • "rating": 4,
  • "installation_id": "inst_12345",
  • "review_text": "The connector works well but could use more features."
}

Response samples

Content type
application/json
{
  • "rating_id": "rat_67890",
  • "connector_id": "con_54321",
  • "rating": 4,
  • "review_text": "The connector works well but could use more features.",
  • "updated_at": "2023-10-05T14:48:00.000Z"
}

Retrieve ratings for a specific connector

Explore the diverse perspectives of users by accessing ratings for any given connector on the HUMAN marketplace. This endpoint offers a glimpse into the community's feedback, essential for refining and optimizing AI-human collaboration tools. Dive into the data to understand the connector's performance and user satisfaction, while contributing to an open ecosystem of trust and innovation.

Responses

Response samples

Content type
application/json

Ratings for connector showing user feedback and summary statistics.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "summary": {
    }
}

Preview Marketplace Bundle Installation

Embark on a journey to seamlessly preview the installation of marketplace bundles. This endpoint offers a glimpse into the future, enabling organizations to assess the impact and compatibility of installing a new bundle before committing to it, ensuring smooth transitions and maintaining operational harmony.

Request Body schema: application/json
required
asset_id
required
string

The unique identifier for the asset bundle.

org_did
required
string

The decentralized identifier for the organization.

preset
string
Enum: "safe" "autopilot" "custom"

The installation preset to use, offering various levels of automation and safety.

Responses

Request samples

Content type
application/json

Previewing the installation of a bundle with standard safety preset in the ACME organization.

{
  • "asset_id": "bundle12345",
  • "org_did": "did:human:acme-org",
  • "preset": "safe"
}

Response samples

Content type
application/json
{
  • "preview": {
    },
  • "policy_compatibility": {
    }
}

Export marketplace bundle for offline review

In the world of secure data management, reviewing asset bundles offline is crucial for maintaining air-gap security. This endpoint facilitates the export of a signed bundle, complete with an HMAC manifest and member digests, allowing you to safely review your assets without an active network connection.

Request Body schema: application/json
required
bundle_asset_id
required
string

The unique identifier of the bundle to export

Responses

Request samples

Content type
application/json

Exporting the asset bundle with ID 'bundle-12345' for review by Acme Corp's security team.

{
  • "bundle_asset_id": "bundle-12345"
}

Response samples

Content type
application/json
{
  • "hmac_manifest": "hmac-abc123",
  • "member_digests": [
    ]
}

Compensate bundle installation rollback

When an AI bundle installation encounters an unforeseen rollback or partial failure, the compensate endpoint restores balance. By invoking this endpoint, operators ensure the orchestration environment remains consistent, resolving issues without manual intervention.

Request Body schema: application/json
required
bundle_installation_id
required
string

Unique identifier of the bundle installation

org_did
required
string

Decentralized Identifier (DID) of the organization

Responses

Request samples

Content type
application/json

Request to compensate a rollback for 'acme' organization

{
  • "bundle_installation_id": "abc123xyz",
  • "org_did": "did:human:acme-456"
}

Response samples

Content type
application/json
{
  • "message": "Compensation completed successfully for bundle installation abc123xyz"
}

Retrieve deduplicated partner incident feed

Gain insights into marketplace incidents impacting your assets with this endpoint. By leveraging your Passport, it filters and summarizes incidents, providing a concise view of issues that matter most to your organization. Discover the root causes and suggested fixes quickly, ensuring you can take prompt action.

Responses

Response samples

Content type
application/json

Retrieves the incident feed for a publisher with Passport ID 'publisher-123'.

{
  • "publisher_id": "publisher-123",
  • "generated_at": "2023-10-15T12:34:56Z",
  • "data": [
    ]
}

Retrieve Marketplace Asset Templates

Explore the HUMAN Marketplace catalog, a vibrant selection of templates, connectors, muscles, and policy packs. This endpoint empowers developers by providing a curated list of available assets, enabling seamless integration of HUMAN capabilities into your projects.

Responses

Response samples

Content type
application/json

Acme Corp retrieves the latest templates for their AI project, ensuring they have the most up-to-date resources.

{
  • "data": [
    ],
  • "limit": 2,
  • "cursorField": "id",
  • "hasMore": true
}

Retrieve marketplace template details

Explore the intricate details of a specific template from our marketplace. This endpoint serves as your gateway to understanding the capabilities and assets encapsulated within each template, bringing clarity and depth to your selection process.

Responses

Response samples

Content type
application/json

A comprehensive template used by Acme Corp for processing invoices.

{
  • "id": "t123",
  • "slug": "acme-invoice-template",
  • "name": "Acme Invoice",
  • "description": "A template for automating invoice processing at Acme Corp.",
  • "manifest_json": {
    },
  • "version": "1.2.0",
  • "asset_type": "financial"
}

Install a Marketplace Template

Install a chosen template from the marketplace into your organization's workspace. This endpoint empowers organizations to rapidly deploy pre-configured workflows or agents, streamlining operations and enhancing productivity.

Request Body schema: application/json
required
name_override
string

A new name for the template within your organization.

Responses

Request samples

Content type
application/json

Install a template with a custom name.

{
  • "name_override": "Custom Workflow for Acme Inc."
}

Response samples

Content type
application/json

A workflow template named 'Custom Workflow for Acme Inc.' was installed successfully.

{
  • "id": "workflow-12345",
  • "name": "Custom Workflow for Acme Inc.",
  • "orgId": "org-acme"
}

Retrieve list of marketplace connectors

Explore the vast ecosystem of connectors available on the HUMAN Marketplace. This endpoint provides a curated list of connectors, enabling seamless integration and enhancing the capability graph of your organization. Whether you're looking to expand your toolkit or ensure compatibility, this list is your gateway to innovation.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieve active muscles for organization

Explore the vibrant ecosystem of skills, known as 'muscles', installed in your organization’s HUMAN platform. This endpoint is your gateway to discovering the active tools your team has harnessed, ensuring seamless task orchestration and AI collaboration.

Responses

Response samples

Content type
application/json

Acme Corp retrieves a list of their active marketplace muscles.

{
  • "data": [
    ]
}

Retrieve available policy packs

Explore the curated collection of policy packs designed to enhance your Human-AI orchestration with standardized governance and compliance measures. This endpoint is your gateway to understanding the safeguards in place for secure and auditable AI operations.

Responses

Response samples

Content type
application/json

An example of a policy pack with governance features.

{
  • "data": [
    ]
}

Apply a Policy Pack to Marketplace

This endpoint allows you to apply a specified policy pack to a marketplace, ensuring the seamless integration of compliance and security measures. By orchestrating policy applications, HUMAN facilitates a streamlined approach to managing marketplace operations with confidence.

Request Body schema: application/json
required
dry_run
boolean

If true, the policy pack will not actually be applied, allowing you to preview any changes.

Responses

Request samples

Content type
application/json

Demonstrating a dry run to preview policy effects without applying them.

{
  • "dry_run": true
}

Response samples

Content type
application/json

The policy pack was applied to the marketplace with ID pid-12345.

{
  • "applied": true,
  • "pack_id": "pid-12345"
}

Retrieve active capabilities by intent family

Dive into the world of HUMAN's orchestration, where each capability is a piece in the grand puzzle of AI and human collaboration. This endpoint fetches active capabilities tailored to a specified intent family, allowing organizations to seamlessly integrate the right skills for their needs.

Responses

Response samples

Content type
application/json

Shows capabilities for the 'set_up_automation' intent family.

{
  • "intent_family": "set_up_automation",
  • "count": 2,
  • "data": [
    ]
}

Installations

Retrieve the organization's connector installations

Explore the landscape of connectors your organization has entrusted to carry out crucial tasks. This endpoint unveils the tapestry of installations, helping you manage and optimize the technological prowess at your disposal.

Responses

Response samples

Content type
application/json

Retrieve a list of active connectors installed by the 'acme' organization.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Update Connector Installation Details

This endpoint allows organizations to update the configuration or status of a specific connector installation. By enabling such updates, organizations can ensure their integrations remain effective and responsive to changing business needs.

Request Body schema: application/json
required
status
string
Enum: "active" "suspended"

The desired status for the installation.

config
object

The configuration settings for the installation.

Responses

Request samples

Content type
application/json
Example

This example demonstrates updating an installation's status to 'active'.

{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "installation_id": "install-12345",
  • "status": "active",
  • "config": {},
  • "updated_at": "2023-10-01T14:48:00.000Z"
}

Sessions

Exchange Session for Scoped Delegation Token

Transform your session token into a powerful delegation token, granting you precise capabilities across the HUMAN API. Whether you're managing tasks or accessing resources, this endpoint empowers you to define the scope of your activities securely.

Request Body schema: application/json
required
capabilities
Array of strings

List of requested capabilities. Defaults to a standard set if omitted.

orgDid
string

Optional organizational DID for role-based scope.

required_verification_tier
number

Minimum verification tier required for this delegation.

required_identity_tier
number

Minimum identity tier required for this delegation.

duration_seconds
number

Duration for which the delegation token is valid, in seconds.

environment
string

Specific environment constraints for the delegation.

risk_level
string
Enum: "low" "standard" "high"

Risk level associated with the delegation.

Responses

Request samples

Content type
application/json
Example

Request with default capabilities and 24-hour duration.

{
  • "capabilities": [ ],
  • "duration_seconds": 86400
}

Response samples

Content type
application/json
{
  • "delegation_id": "del_123456789",
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "passport_id": "did:example:user123",
  • "did": "did:example:user123",
  • "capabilities": [
    ],
  • "verification_tier": 2,
  • "identity_tier": 3,
  • "created_at": "2023-10-01T12:00:00Z",
  • "expires_at": "2023-10-02T12:00:00Z",
  • "has_companion_cp_read": false
}

Stream Duplex Session Events via SSE

Experience the continuous flow of events from a duplex session, leveraging Server-Sent Events (SSE) to keep you updated in real-time. This endpoint ensures you are at the forefront of session activity, providing insights and state changes as they happen.

Responses

Response samples

Content type
application/json
Example

Streaming active events from a live session.

"data: {\"type\":\"interaction\",\"detail\":\"user joined\",\"sessionId\":\"session123\",\"timestamp\":\"2023-10-12T07:20:50.52Z\"}\n\n"

Retrieve active MCP sessions

Discover the active and valid sessions for your cryptographic identity with this endpoint. It's designed to empower organizations, like Acme Corp, by listing ongoing sessions securely linked to a Passport, ensuring transparency and control over session activity.

Responses

Response samples

Content type
application/json

An example response showing active sessions for a Passport.

{
  • "sessions": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Register or update MCP session details

This endpoint allows internal components of the HUMAN platform to register or update sessions for multi-capability processing (MCP). By managing session lifecycles, it ensures seamless orchestration of tasks across human and AI agents under secure conditions.

Request Body schema: application/json
required
session_id
required
string

Unique identifier for the session

passport_id
required
string

Cryptographic identity of the agent

org_did
required
string

Decentralized identifier for the organization

scopes
Array of strings

List of permissions granted to the session

client_name
string

Name of the client creating the session

plan_tier
string or null

Service plan tier (if applicable)

expires_at
required
string <date-time>

Expiration timestamp for the session

Responses

Request samples

Content type
application/json

Registers a session for the 'acme' organization with specific scopes and a premium plan tier.

{
  • "session_id": "session_12345",
  • "passport_id": "passport_abcde",
  • "org_did": "did:humanos:acme",
  • "scopes": [
    ],
  • "client_name": "Acme Client",
  • "plan_tier": "premium",
  • "expires_at": "2023-12-31T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Compliance

Verify Deployment Compliance Status

Discover the compliance heartbeat of a node, ensuring its alignment with the HUMAN protocol. This endpoint is a beacon of transparency, allowing any node to validate the integrity of another's deployment operations.

Responses

Response samples

Content type
application/json

Example of a compliant node's response, showing a healthy and synchronized deployment.

{
  • "deployment_id": "node_12345",
  • "protocol_version": "0.1",
  • "compliance": {
    },
  • "invariants": {
    },
  • "signature": "dXNlcm5hbWU6cGFzc3dvcmQ="
}

Retrieve deployment's verification status

In an interconnected digital ecosystem, understanding your deployment's verification status is pivotal. This endpoint unravels whether your deployment's passports are network verified or confined to local validation, a crucial distinction in maintaining security integrity.

Responses

Response samples

Content type
application/json

An example scenario where the deployment is verified only locally.

{
  • "network_verification": "local_only",
  • "explanation": "Passports on this deployment are verified locally. Network-wide verification requires distributed ledger integration (v0.3).",
  • "mitigations": [
    ],
  • "risks": {
    },
  • "recommendations": [
    ]
}

Generate compliance activity report

Dive into the depths of your organization's compliance activities with this endpoint, which meticulously crafts a report detailing event occurrences over a specified time window. This ensures accountability and transparency, painting a clear picture of your operational integrity.

Request Body schema: application/json
required
start_date
string <date-time>

The start date for the report window. Only events from this date forward will be included.

end_date
string <date-time>

The end date for the report window. Only events up to this date will be included.

report_type
required
string
Enum: "summary" "detailed"

The type of report to generate. 'summary' provides a high-level overview, while 'detailed' offers in-depth insights.

Responses

Request samples

Content type
application/json

Generate a summary report for the first quarter of the year.

{
  • "start_date": "2023-01-01T00:00:00Z",
  • "end_date": "2023-03-31T23:59:59Z",
  • "report_type": "summary"
}

Response samples

Content type
application/json

A successful generation of a summary report showing event counts.

{
  • "report_type": "summary",
  • "generated_at": "2023-10-01T12:00:00Z",
  • "window": {
    },
  • "counts_by_event_type": {
    }
}

Initiate a fraud policy review

This endpoint empowers organizations to initiate a review of potential fraud activities within their systems. By submitting relevant case references, organizations can ensure a systematic and documented approach to fraud detection and mitigation. This service plays a critical role in enhancing transparency and accountability in financial transactions.

Request Body schema: application/json
required
One of
case_ref
required
string

Unique reference for the fraud case

case_id
string

Alternate identifier for the fraud case

Responses

Request samples

Content type
application/json

Initiating a fraud review using a case reference

{
  • "case_ref": "FRD-20231010-001"
}

Response samples

Content type
application/json
{
  • "review_id": "cp_fpol_123456",
  • "case_ref": "FRD-20231010-001",
  • "status": "recorded",
  • "reviewed_at": "2023-10-10T14:48:00.000Z"
}

Retrieve audit decisions within an organization

Dive into the decision-making process of your organization with the power of audit insights. Understanding who decided what and why is crucial for transparent operations and compliance. This endpoint equips organizations with the ability to pull detailed decision records, ensuring accountability and traceability.

Responses

Response samples

Content type
application/json

Retrieve decisions for the 'acme' organization, focusing on a specific workflow within a date range.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "updated_at",
  • "hasMore": false,
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Retrieve audit override events history

Dive into the past and explore audit override events for your organization. This endpoint offers a window into the decisions that altered the usual course of operations, enabling transparency and accountability. Use it to track changes, understand discrepancies, and ensure compliance with established protocols.

Responses

Response samples

Content type
application/json

Shows a paginated list of past override events for the organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "occurred_at",
  • "hasMore": true,
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Create and store audit evidence bundles

This endpoint is a crucial part of maintaining transparency and trust within the HUMAN ecosystem. It enables organizations to submit decision-making evidence, ensuring accountability and providing a clear audit trail. By storing these bundles, it supports robust AI governance and compliance efforts.

Request Body schema: application/json
required
decision_ids
required
Array of strings

List of decision IDs related to the evidence bundle.

format
string

Format in which the evidence bundle should be stored, defaults to 'ops'.

generated_by
string

Identifier for the entity generating the evidence, defaults to the agent audit API if not provided.

Responses

Request samples

Content type
application/json

A typical example where an organization submits an evidence bundle for multiple decisions.

{
  • "decision_ids": [
    ],
  • "format": "json",
  • "generated_by": "acmeCorpAuditTool"
}

Response samples

Content type
application/json
{
  • "bundle_id": "bundle-98765",
  • "status": "created"
}

Fetch audit challenges for organization

Retrieve a list of audit challenges associated with your organization, enabling you to track and manage compliance and decision-making processes. This endpoint is vital for organizations like 'acme' to ensure transparency and accountability in their AI task orchestration.

Responses

Response samples

Content type
application/json

A realistic example where 'acme' organization fetches audit challenges with pagination.

{
  • "data": [
    ],
  • "limit": 2,
  • "cursorField": "createdAt",
  • "hasMore": true,
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Retrieve a specific audit challenge case

Uncover the story behind a specific challenge in your organization's audit trail. Every challenge tells a tale of compliance and decision-making, ensuring transparency and accountability within the HUMAN ecosystem.

Responses

Response samples

Content type
application/json

Retrieving an audit challenge case for organization with DID 'did:human:acme'.

{
  • "id": "challenge-123",
  • "decision_id": "decision-456",
  • "org_did": "did:human:acme",
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Retrieve audit decisions with flexible filtering

Explore the audit decisions made within your organization, leveraging powerful filters to navigate complex data. This endpoint is your window into the decision-making process, enabling transparency and compliance by surfacing the 'who,' 'what,' and 'why' behind each decision. By understanding these decisions, organizations can better orchestrate their human and AI resources, ensuring decisions align with their strategic goals.

Responses

Response samples

Content type
application/json

Acme Corp requests to view recent audit decisions, filtered by risk level and status.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursor": "2023-10-02T12:00:00Z",
  • "hasMore": false,
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Deployment

Verify Deployment Compliance Status

Discover the compliance heartbeat of a node, ensuring its alignment with the HUMAN protocol. This endpoint is a beacon of transparency, allowing any node to validate the integrity of another's deployment operations.

Responses

Response samples

Content type
application/json

Example of a compliant node's response, showing a healthy and synchronized deployment.

{
  • "deployment_id": "node_12345",
  • "protocol_version": "0.1",
  • "compliance": {
    },
  • "invariants": {
    },
  • "signature": "dXNlcm5hbWU6cGFzc3dvcmQ="
}

Deploy an agent with identity minting

Embark on the journey of deploying an agent where identity and capability converge. This endpoint mints a Passport for your agent, anchoring its identity in the distributed ledger and equipping it with the skills needed for its mission. It's not just deployment; it's the birth of a digital entity.

Request Body schema: application/json
required
required
object
profile
string
Default: "hosted"

Responses

Request samples

Content type
application/json

Deploys an agent named 'invoice-processor' for the 'acme' organization with AI capabilities.

{
  • "manifest": {
    }
}

Response samples

Content type
application/json
null

Reasoning

Execute high-level reasoning tasks

In the realm of innovation, sometimes you just need to think. This endpoint orchestrates AI and human capabilities to tackle tasks ranging from coding to creative work. By balancing costs, complexity, and quality, it ensures your organization's goals are met efficiently.

Request Body schema: application/json
required
required
Array of objects
task
required
string
Enum: "reasoning" "coding" "summarization" "creative" "math" "general"
complexity
required
string
Enum: "simple" "medium" "complex"
budget
required
string
Enum: "minimize" "optimize" "unlimited"
pinned_model
string
entity_id
required
string
temperature
number
max_tokens
integer

Responses

Request samples

Content type
application/json

A request for a medium complexity reasoning task with optimized budget.

{
  • "messages": [
    ],
  • "task": "reasoning",
  • "complexity": "medium",
  • "budget": "optimize",
  • "entity_id": "org_acme",
  • "temperature": 0.7,
  • "max_tokens": 1000
}

Response samples

Content type
application/json
null

AI Orchestration

Execute high-level reasoning tasks

In the realm of innovation, sometimes you just need to think. This endpoint orchestrates AI and human capabilities to tackle tasks ranging from coding to creative work. By balancing costs, complexity, and quality, it ensures your organization's goals are met efficiently.

Request Body schema: application/json
required
required
Array of objects
task
required
string
Enum: "reasoning" "coding" "summarization" "creative" "math" "general"
complexity
required
string
Enum: "simple" "medium" "complex"
budget
required
string
Enum: "minimize" "optimize" "unlimited"
pinned_model
string
entity_id
required
string
temperature
number
max_tokens
integer

Responses

Request samples

Content type
application/json

A request for a medium complexity reasoning task with optimized budget.

{
  • "messages": [
    ],
  • "task": "reasoning",
  • "complexity": "medium",
  • "budget": "optimize",
  • "entity_id": "org_acme",
  • "temperature": 0.7,
  • "max_tokens": 1000
}

Response samples

Content type
application/json
null

Create and route a new intent

This endpoint breathes life into your HUMAN platform by capturing and shaping user intents for task orchestration. With a blend of AI and human oversight, it transforms raw inputs into actionable intents, ensuring each task is routed with precision and safety.

Request Body schema: application/json
required
raw_input
required
string

The unprocessed text representing the user's intent

source_surface
string
Enum: "companion" "control_plane" "workflow_designer" "agent_builder"

The interface from which the intent originated

modality
string
Enum: "text" "voice" "image" "document" "form" "mixed" "template"

The format of the input data

template_id
string

Optional ID for a specific template if applicable

Responses

Request samples

Content type
application/json

Illustrates a basic text intent submitted from the control plane interface.

{
  • "raw_input": "Process the latest invoices for approval",
  • "source_surface": "control_plane",
  • "modality": "text",
  • "template_id": "invoice-template-001"
}

Response samples

Content type
application/json
{
  • "intent_id": "intent-123456",
  • "status": "routing_in_progress"
}

Compile AI task intent brief

This endpoint transforms a raw intent brief into an actionable resolution plan. It orchestrates AI capabilities to meet organizational needs, ensuring each intent is feasible and compliant. Imagine a team at 'acme' orchestrating invoice approvals with AI precision and human oversight.

Request Body schema: application/json
required
override_capability_ids
Array of strings <capability://> [ items <capability:// > ]

Responses

Request samples

Content type
application/json

Overrides default capabilities with specified ones for a custom AI task resolution.

{
  • "override_capability_ids": [
    ]
}

Response samples

Content type
application/json

Compilation of an intent brief into a resolution plan for invoice processing.

{
  • "resolution_plan": {
    },
  • "brief_id": "intent123"
}

AI Models

Retrieve available AI models and capabilities

Explore the dynamic landscape of AI models with HUMAN's orchestration endpoint. By filtering models based on provider, status, and capabilities, organizations can harness the right blend of reasoning and coding prowess to meet their unique needs. This endpoint serves as a gateway to understanding and leveraging the diverse skills housed within the HUMAN network.

Responses

Response samples

Content type
application/json

Acme Corp is filtering models by OpenAI provider and active status, seeking top-tier reasoning capabilities.

{
  • "models": [
    ]
}

Retrieve AI Model Performance Metrics

Delve into the operational excellence of your AI model by retrieving performance metrics that span request volumes, success rates, latency, and cost. This endpoint empowers you to make data-driven decisions by providing insights into model efficiency over the past 30 days, dissected by complexity tiers.

Responses

Response samples

Content type
application/json

Fetches detailed performance metrics for the 'gpt-4-turbo' model, offering insights into its operational behavior.

{
  • "model_id": "gpt-4-turbo",
  • "total_requests": 1234,
  • "success_rate": 0.98,
  • "avg_latency_ms": 2500,
  • "avg_cost_usd": 0.025,
  • "by_complexity": {
    }
}

Model

Submit Model Benchmark Results

Elevate the capabilities of your AI models by submitting benchmark results. This endpoint allows you to track the performance of your models across different benchmark suites, ensuring continuous improvement and reliability. Record the prowess of your models and contribute to a distributed ledger of AI excellence.

Request Body schema: application/json
required
model_id
required
string

Unique identifier for the AI model.

benchmark_type
required
string

Type of benchmark conducted (e.g., 'reasoning').

benchmark_suite
required
string

Name of the benchmark suite used (e.g., 'mmlu').

score
required
number

Performance score out of 100.

run_at
required
string <date-time>

Timestamp of when the benchmark was run.

run_by
string

Identifier of the system or user that ran the benchmark.

test_cases_passed
integer

Number of test cases the model passed.

test_cases_total
integer

Total number of test cases.

raw_results
object

Detailed raw results of the benchmark.

Responses

Request samples

Content type
application/json

Submitting reasoning benchmark results for Acme Corp's GPT-4 Turbo model.

{
  • "model_id": "gpt-4-turbo",
  • "benchmark_type": "reasoning",
  • "benchmark_suite": "mmlu",
  • "score": 86.4,
  • "run_at": "2024-01-25T10:30:00Z",
  • "run_by": "system",
  • "test_cases_passed": 432,
  • "test_cases_total": 500,
  • "raw_results": {
    }
}

Response samples

Content type
application/json
{
  • "id": "bench_123",
  • "model_id": "gpt-4-turbo",
  • "benchmark_type": "reasoning",
  • "benchmark_suite": "mmlu",
  • "score": 86.4,
  • "run_at": "2024-01-25T10:30:00Z"
}

Benchmarking

Submit Model Benchmark Results

Elevate the capabilities of your AI models by submitting benchmark results. This endpoint allows you to track the performance of your models across different benchmark suites, ensuring continuous improvement and reliability. Record the prowess of your models and contribute to a distributed ledger of AI excellence.

Request Body schema: application/json
required
model_id
required
string

Unique identifier for the AI model.

benchmark_type
required
string

Type of benchmark conducted (e.g., 'reasoning').

benchmark_suite
required
string

Name of the benchmark suite used (e.g., 'mmlu').

score
required
number

Performance score out of 100.

run_at
required
string <date-time>

Timestamp of when the benchmark was run.

run_by
string

Identifier of the system or user that ran the benchmark.

test_cases_passed
integer

Number of test cases the model passed.

test_cases_total
integer

Total number of test cases.

raw_results
object

Detailed raw results of the benchmark.

Responses

Request samples

Content type
application/json

Submitting reasoning benchmark results for Acme Corp's GPT-4 Turbo model.

{
  • "model_id": "gpt-4-turbo",
  • "benchmark_type": "reasoning",
  • "benchmark_suite": "mmlu",
  • "score": 86.4,
  • "run_at": "2024-01-25T10:30:00Z",
  • "run_by": "system",
  • "test_cases_passed": 432,
  • "test_cases_total": 500,
  • "raw_results": {
    }
}

Response samples

Content type
application/json
{
  • "id": "bench_123",
  • "model_id": "gpt-4-turbo",
  • "benchmark_type": "reasoning",
  • "benchmark_suite": "mmlu",
  • "score": 86.4,
  • "run_at": "2024-01-25T10:30:00Z"
}

Prompts

Retrieve readable prompts with filtering

Explore the universe of prompts you're authorized to view, tailored to your specific scopes and needs. This endpoint empowers users to efficiently navigate through a curated list of prompts, filtered by pertinent criteria such as scope, type, or namespace, ensuring only relevant prompts are presented.

Responses

Response samples

Content type
application/json

A list of prompts available to Acme Corp's user with read access.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": 1
}

Retrieve the active version of a prompt

In the dynamic world of prompts, accessing the latest version is crucial for keeping your applications in sync. This endpoint allows you to retrieve the active version of a specific prompt, ensuring that you are always working with the most current information. It supports both short keys and full URIs, making it versatile for various use cases.

Responses

Response samples

Content type
application/json

Retrieves the active version details for a prompt with a short key.

{
  • "version": "v2.3.1",
  • "content": "Welcome to the new era of AI-driven orchestration."
}

Retrieve versions of a specific prompt

Explore the evolutionary journey of your prompts by listing all their versions. This endpoint empowers organizations to track changes, ensuring clarity and accountability in modifications over time. Whether for audit purposes or creative exploration, understanding the version history is pivotal.

Responses

Response samples

Content type
application/json

A detailed look at all versions of the 'invoice-processing' prompt.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "version",
  • "totalCount": 2
}

Retrieve a specific prompt version

Uncover the rich history of your creative assets by retrieving a specific version of a prompt. This endpoint exists to empower organizations to track their content evolution, ensuring that every iteration is preserved and accessible for future reference.

Responses

Response samples

Content type
application/json
null

Publish a new version of a prompt

Publishing prompts is at the heart of dynamic content orchestration within HUMAN. This endpoint allows you to release updates, ensuring your AI tasks are fueled with the latest and greatest instructions. It's not just about updates; it's about enhancing the AI-human collaboration with precision and clarity.

Request Body schema: application/json
required
version
required
string

Semantic version of the prompt, e.g., '1.0.0'.

content
required
string

The core text or body of the prompt.

meta
required
object

Metadata about the prompt, such as namespace and ID.

input_schema
object

Optional schema detailing expected input structure.

Responses

Request samples

Content type
application/json

Publishing the first version of a new prompt for the 'acme' organization.

{
  • "version": "1.0.0",
  • "content": "Welcome to the Acme AI platform!",
  • "meta": {
    },
  • "input_schema": {
    }
}

Response samples

Content type
application/json
null

Deprecate a specific prompt version

This endpoint allows you to mark a specific version of a prompt as deprecated. It plays a crucial role in maintaining the integrity of your prompts' lifecycle, ensuring that outdated or incorrect versions are no longer in active use. By deprecating a version, you safeguard the quality and consistency of tasks processed by your organization.

Responses

Response samples

Content type
application/json

A prompt version is successfully deprecated.

{
  • "prompt_uri": "prompt://acme/invoice-processing",
  • "version": "v1.2.3",
  • "status": "deprecated",
  • "deprecated_at": "2023-11-02T14:30:00Z"
}

Access Control

Retrieve readable prompts with filtering

Explore the universe of prompts you're authorized to view, tailored to your specific scopes and needs. This endpoint empowers users to efficiently navigate through a curated list of prompts, filtered by pertinent criteria such as scope, type, or namespace, ensuring only relevant prompts are presented.

Responses

Response samples

Content type
application/json

A list of prompts available to Acme Corp's user with read access.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": 1
}

Revoke a Human API Signing Key

This endpoint allows you to revoke an API signing key associated with a Human Passport. By invalidating the specified key, you ensure that it can no longer be used to authenticate requests, enhancing security and control over your API access. This is particularly useful when a key is compromised or no longer needed.

Responses

Response samples

Content type
application/problem+json

Occurs when the keyId format does not match the expected pattern.

{}

Create a new audit grant

In the HUMAN platform, oversight and transparency are paramount. This endpoint empowers organizations to delegate audit rights through cryptographic Passports, ensuring that the right individuals can review and validate transactions. By facilitating controlled access, it maintains trust and security within the system.

Request Body schema: application/json
required
grantee_passport_id
required
string

The Passport ID of the grantee who receives the audit rights.

granter_passport_id
string

The Passport ID of the granter delegating the audit rights.

purpose
string

The reason for granting the audit rights, e.g., 'audit_review'.

mode
string

The mode of audit rights, e.g., 'delegated_investigation'.

object

The scope of the audit rights, defined as a JSON object.

expires_at
string <date-time>

The expiration date and time for the audit grant.

Responses

Request samples

Content type
application/json

Delegating audit rights to an external auditor for compliance checks.

{
  • "grantee_passport_id": "passport:12345",
  • "granter_passport_id": "passport:67890",
  • "purpose": "compliance_audit",
  • "mode": "delegated_investigation",
  • "scope": {
    },
  • "expires_at": "2023-12-31T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "grant_id": "agrant:1234567890"
}

Retrieve organization's audit access log

Explore the intricate dance of responsibility and transparency with our audit access log, where organizational oversight meets accountability. This endpoint empowers audit administrators to meticulously track who accessed what and when, ensuring that every digital interaction is recorded for posterity.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "accessed_at",
  • "hasMore": false
}

Retrieve a specific canvas by ID

Unveil the intricate details of a specific canvas, a dynamic workspace within the HUMAN platform. This endpoint empowers users to access canvases that they are authorized to view, facilitating collaboration and innovation within secure boundaries.

Responses

Response samples

Content type
application/json

This example demonstrates a successful retrieval of an 'acme' organization's invoice processing canvas.

{
  • "spec": {
    }
}

Organizations

Retrieve organizations for a passport

Discover the organizations where your cryptographic identity, or Passport, is a recognized member. This endpoint allows you to navigate through your affiliations, providing a seamless connection to your roles and responsibilities across the HUMAN network.

Responses

Response samples

Content type
application/json

A user fetches their affiliated organizations.

{
  • "data": [
    ],
  • "limit": 2,
  • "nextCursor": "eyJjcmVhdGVkX2F0IjoiMjAyMy0wOC0yMlQwODoyMTozM1oifQ=="
}

Retrieve organization communication settings

Dive into the communication preferences of an organization with this endpoint. Fetching these settings allows you to understand how the organization presents itself in communications, ensuring consistent messaging and proper routing of replies. This is crucial for maintaining a polished and professional external appearance.

Responses

Response samples

Content type
application/json

Communication settings for Acme Corporation, illustrating a typical setup.

{
  • "org_did": "did:human:acme123",
  • "send_mode": "batch",
  • "from_display_name": "Acme Support",
  • "from_email": "support@acme.com",
  • "reply_to_email": "noreply@acme.com",
  • "legal_footer": "© 2023 Acme Corporation. All rights reserved.",
  • "updated_at": "2023-09-15T14:00:00Z"
}

Retrieve organization's installed muscles

In the heart of the HUMAN platform, organizations harness the power of 'muscles'—modular skills to augment human capabilities. This endpoint allows you to explore the muscles currently installed for a specific organization, enabling you to manage and optimize skill resources. Delve into the dynamic world of skill orchestration, where AI and human skills converge.

Responses

Response samples

Content type
application/json

An overview of muscles installed in Acme Corp, showcasing active skill modules.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "installed_at",
  • "hasMore": false
}

Install a new muscle for an organization

In the ever-evolving orchestration of human and AI, installing a 'muscle' represents empowering your organization with new capabilities. This endpoint ensures your organization is equipped with the right tools, validating asset and version, and securing the necessary connectors for a seamless integration.

Request Body schema: application/json
required
muscle_id
required
string

Unique identifier in publisher.name format.

version
required
string

Semantic version of the muscle being installed.

asset_id
string

Optional ID of the marketplace asset if specifying an asset.

config
object

Configuration settings for the muscle.

Responses

Request samples

Content type
application/json

Installing the spreadsheet processing muscle for data analytics.

{
  • "muscle_id": "human.spreadsheets",
  • "version": "1.0.0",
  • "asset_id": "asset-1234",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "org_did": "did:human:org:acme",
  • "muscle_id": "human.spreadsheets",
  • "version_installed": "1.0.0",
  • "asset_id": "asset-1234",
  • "config": {
    },
  • "installed_by_did": "did:human:agent:installer",
  • "status": "active"
}

Retrieve workforce queue details for organization

Unleash the power of your organization by accessing a detailed view of workforce queues. This endpoint allows you to harness insights into task distribution, easily identifying pending and active tasks across different queues. Perfect for managers seeking to optimize task allocation and ensure smooth operations.

Responses

Response samples

Content type
application/json

A snapshot of task queues for Acme Corp, illustrating pending and active tasks.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": false
}

Retrieve organization's CP extensions

Explore the vibrant ecosystem of Control Panel extensions tailored for your organization. This endpoint empowers admins by offering a detailed list of extensions, showcasing each tool's capabilities and potential to enhance your organization's operational efficiency.

Responses

Response samples

Content type
application/json
{
  • "org_did": "did:example:123456789",
  • "extensions": [
    ]
}

Retrieve organization's active companion modules

Unveil the ensemble of companion modules that your organization actively leverages to enhance its capabilities. This endpoint empowers you with insights into each module's specifics, facilitating strategic orchestration and informed decision-making.

Responses

Response samples

Content type
application/json

An example response showing Acme Corp's active companion modules.

{
  • "org_did": "did:human:acme",
  • "companion_modules": [
    ]
}

Retrieve Active Workforce Modules

Unveil the capabilities of your organization by retrieving active workforce modules. This endpoint empowers you to understand and manage the skills and tools available within your organization, ensuring optimal orchestration of human and AI efforts.

Responses

Response samples

Content type
application/json

A list of active workforce modules for Acme Corp, showcasing their installed capabilities.

{
  • "org_did": "did:example:123456",
  • "modules": [
    ]
}

Retrieve Visible Organization Passports

Explore the world of cryptographic identities with the HUMAN platform's Passport retrieval. This endpoint unveils the passports of organizations where you are a recognized founder or where your organization is a delegation grantor, providing a window into the interconnected web of legal entities. Experience seamless navigation through the Capability Graph as you harness the power of AI to track skills and ensure task safety with HumanOS.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Reject a proposal within an organization

In the dynamic interplay of human intellect and AI, proposals drive evolution. This endpoint empowers founders to decisively reject proposals that no longer align with organizational vision, ensuring agility and adherence to core values.

Request Body schema: application/json
required
One of
rejected_by
required
string^did:human:.*$

DID of the founder rejecting the proposal

Responses

Request samples

Content type
application/json

Example illustrating rejection by a valid founder DID.

{
  • "rejected_by": "did:human:1234abcd"
}

Response samples

Content type
application/json
{
  • "proposal_id": "proposal-5678efgh",
  • "status": "rejected",
  • "rejected_by": "did:human:1234abcd"
}

Organization Management

Create a new organization in the HUMAN protocol

This endpoint orchestrates the creation of a new organization, weaving together identity, skills, and AI safety into a cohesive entity. It serves as the gateway for enterprising teams to join the HUMAN network, enabling them to harness distributed ledger technology for provenance and task orchestration.

Request Body schema: application/json
required
org_did
required
string

Decentralized identifier for the organization.

name
required
string

Human-readable name of the organization.

slug
string

URL-friendly identifier, optional.

deployment_mode
string
Enum: "cloud" "on-prem"

Deployment preference, default is 'cloud'.

data_residency_tier
string
Enum: "global" "regional"

Desired data residency policy, default is 'global'.

autonomy_profile
string
Enum: "balanced" "high" "low"

Autonomy level for AI task routing, default is 'balanced'.

Responses

Request samples

Content type
application/json

Creating an organization for Acme Corp with default settings.

{
  • "org_did": "did:org:acme-corp",
  • "name": "Acme Corp",
  • "slug": "acme-corp",
  • "deployment_mode": "cloud",
  • "data_residency_tier": "global",
  • "autonomy_profile": "balanced"
}

Response samples

Content type
application/json
{
  • "org_did": "did:org:acme-corp",
  • "name": "Acme Corp",
  • "slug": "acme-corp",
  • "deployment_mode": "cloud",
  • "data_residency_tier": "global",
  • "autonomy_profile": "balanced",
  • "member_roles": {
    },
  • "vault_endpoint": "https://api.humanprotocol.com/v1/vault"
}

Initiate Employee Onboarding with Verification

Embark on a seamless journey to onboard new employees by creating their records and initiating the verification process. This endpoint empowers organizations to swiftly integrate new members into their ranks, ensuring they are equipped with a digital identity that links them securely to their workplace.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Update organizational details securely

Refine the identity and configuration of your organization within the HUMAN ecosystem. This endpoint empowers administrators to update key organizational attributes, ensuring alignment with evolving goals and compliance requirements. By leveraging this capability, you can effortlessly manage organizational dynamics through cryptographic identity and secure task orchestration.

Request Body schema: application/json
required
name
string

The human-readable name of the organization.

slug
string

A unique identifier for the organization.

logo_url
string

URL to the organization's logo.

deployment_mode
string

Current mode of deployment, e.g., 'development' or 'production'.

data_residency_tier
string

Tier defining data residency restrictions.

data_residency_region
string

Region where data is stored.

autonomy_profile
string

Profile defining organizational autonomy level.

policies
object

Organizational policies in JSON format.

settings
object

Specific settings for organizational configuration.

Responses

Request samples

Content type
application/json

This example demonstrates a request to update the organization's name and switch its deployment mode to 'production'.

{
  • "name": "Acme Corp",
  • "deployment_mode": "production"
}

Response samples

Content type
application/json

The organization Acme Corp's details have been successfully updated.

{
  • "orgDid": "did:human:acme",
  • "name": "Acme Corp",
  • "slug": "acme-corp",
  • "logo_url": "https://example.com/logo.png",
  • "deployment_mode": "production",
  • "data_residency_tier": "premium",
  • "data_residency_region": "us-east-1",
  • "autonomy_profile": "advanced",
  • "policies": {
    },
  • "settings": {
    }
}

Configure Organization Autonomy Profile

Elevate your organization's decision-making capabilities by setting an autonomy profile that aligns with your operational strategy. This endpoint allows you to define how autonomously your systems should operate, striking a balance between human oversight and AI efficiency. Choose from 'Paranoid', 'Balanced', or 'Aggressive' profiles to best suit your organization's needs.

Request Body schema: application/json
required
autonomy_profile
required
string
Enum: "paranoid" "balanced" "aggressive"

Specifies the level of autonomy granted to the organization.

Responses

Request samples

Content type
application/json

Setting the autonomy profile to 'Balanced' for an organization.

{
  • "autonomy_profile": "balanced"
}

Response samples

Content type
application/json

Organization's autonomy profile updated to 'Balanced'.

{
  • "org_did": "did:example:123456",
  • "autonomy_profile": "balanced",
  • "settings": {
    }
}

Create or update task routing rule

Define how tasks are routed by associating them with default queues within your organization. This endpoint empowers automated task distribution, ensuring efficiency and alignment with organizational workflows. By crafting these rules, you enable seamless orchestration between human and AI capabilities, optimizing task management.

Request Body schema: application/json
required
task_type
required
string

The type of task this rule applies to.

default_queue_id
required
string <uuid>

The queue ID where tasks of this type are routed by default.

requires_human
boolean

Indicates if human intervention is required for this task type.

reviewer_count
integer

Number of reviewers needed for tasks of this type.

escalation_policy
object

Policy dictating task escalation parameters.

Responses

Request samples

Content type
application/json

Example of setting a routing rule for invoice processing tasks.

{
  • "task_type": "invoice_processing",
  • "default_queue_id": "8f8c1d1e-1e1b-4b8a-b6e4-2b3a5e6dbe1e",
  • "requires_human": true,
  • "reviewer_count": 2,
  • "escalation_policy": {
    }
}

Response samples

Content type
application/json
{
  • "org_id": "acme-corp",
  • "task_type": "invoice_processing",
  • "default_queue_id": "8f8c1d1e-1e1b-4b8a-b6e4-2b3a5e6dbe1e",
  • "requires_human": true,
  • "reviewer_count": 2,
  • "escalation_policy": {
    }
}

Assets

Explore marketplace assets effortlessly

Venture into the HUMAN marketplace to discover a wide array of assets, curated for global visibility and approved for seamless integration. This endpoint empowers users to browse without authentication, ensuring open access to valuable resources while maintaining security for publisher-specific content.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "hasMore": false,
  • "cursor": "2023-10-01T12:00:00Z"
}

Retrieve Installed Marketplace Assets

In the bustling ecosystem of HUMAN, knowing what assets your organization has harnessed is crucial. This endpoint unveils the list of marketplace assets currently powering an organization, offering insights into the tools and capabilities actively in play. By maintaining a current view of installed assets, organizations can ensure alignment with their strategic goals and optimize their operational efficiency.

Responses

Response samples

Content type
application/json

Shows a list of installed assets for an organization.

{
  • "data": [
    ]
}

Retrieve a marketplace asset by ID

Dive into the dynamic world of HUMAN's marketplace by exploring a specific asset through its unique identifier. This endpoint not only unveils the asset's details but also provides a glimpse into its latest user feedback, fostering an informed decision-making process.

Responses

Response samples

Content type
application/json
{
  • "id": "asset-12345",
  • "name": "AI Invoice Processor",
  • "description": "An AI tool that automates invoice processing for enterprises.",
  • "latest_review": {
    }
}

Install Marketplace Asset to Organization

Seamlessly integrate pre-approved marketplace assets into your organization using the HUMAN platform. This endpoint facilitates the installation process by ensuring assets meet organizational policies and trust tiers, empowering organizations to expand their capabilities securely.

Request Body schema: application/json
required
asset_id
required
string

Unique identifier for the asset to be installed.

org_did
required
string

Decentralized identifier (DID) of the organization.

object

Configuration overrides specific to the asset installation.

preset
string
Default: "safe"

Preset configuration for the asset, defaults to 'safe'.

custom_scopes
Array of strings

Custom scopes required for asset installation.

Responses

Request samples

Content type
application/json

Install a simple extension asset to an organization.

{
  • "asset_id": "asset-12345",
  • "org_did": "did:org:acme",
  • "config_overrides": { },
  • "preset": "safe"
}

Response samples

Content type
application/json
{
  • "result": "Asset 'asset-12345' successfully installed for organization 'did:org:acme'."
}

Retrieve Marketplace Asset Templates

Explore the HUMAN Marketplace catalog, a vibrant selection of templates, connectors, muscles, and policy packs. This endpoint empowers developers by providing a curated list of available assets, enabling seamless integration of HUMAN capabilities into your projects.

Responses

Response samples

Content type
application/json

Acme Corp retrieves the latest templates for their AI project, ensuring they have the most up-to-date resources.

{
  • "data": [
    ],
  • "limit": 2,
  • "cursorField": "id",
  • "hasMore": true
}

Submission

Submit asset for review in marketplace

Embark on a journey to elevate your asset to the marketplace stage by submitting it for a comprehensive review. This process ensures that the asset meets all standards and is ready to make an impact. Replacing the direct publish method, this submission sets the foundation for meticulous vetting, transforming your asset into a beacon of quality.

Request Body schema: application/json
required
name
required
string

The name of the asset.

asset_type
required
string

The type of asset being submitted, such as extension or bundle.

manifest_json
required
object

The manifest detailing the asset's specifications and requirements.

object

Additional metadata for the asset.

visibility
string

The visibility level of the asset, e.g., org_private.

lifecycle_stage
string

The current lifecycle stage of the asset, e.g., production.

Responses

Request samples

Content type
application/json

Submitting an extension asset for review.

{
  • "name": "AcmeExtension",
  • "asset_type": "extension",
  • "manifest_json": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
null

Escalations

Retrieve pending escalation requests

Navigate the intricate web of organizational approvals by fetching escalation requests awaiting attention. Designed for orchestrating critical decision points, this endpoint empowers users to manage and respond to escalated tasks, ensuring timely resolutions and maintaining workflow integrity.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at"
}

Retrieve specific escalation details

Discover the current status of a particular escalation request within your workflow. This endpoint empowers agents and systems to track and manage critical escalations, ensuring timely and effective resolution. By understanding the journey of an escalation, teams can enhance their decision-making and responsiveness.

Responses

Response samples

Content type
application/json

A typical response when fetching an existing escalation

{
  • "id": "esc-12345",
  • "status": "pending",
  • "createdAt": "2023-10-11T14:32:00Z",
  • "updatedAt": "2023-10-12T09:15:00Z",
  • "details": "Awaiting approval from upper management"
}

Respond to an escalation request

In the dynamic world of Human-AI orchestration, escalations can arise requiring human oversight. This endpoint allows authorized users to respond to such escalations, fostering a collaborative decision-making process between humans and AI, ensuring transparency and accountability in task management.

Request Body schema: application/json
required
decision
required
string
Enum: "approved" "approved_with_modifications" "rejected" "request_changes" "delegated" "overridden"

The decision on the escalation

comment
string

Optional comment explaining the decision

modified_params
object

Optional parameters modified during decision

Responses

Request samples

Content type
application/json

An example of approving an escalation with a comment

{
  • "decision": "approved",
  • "comment": "Approved after reviewing the details",
  • "modified_params": { }
}

Response samples

Content type
application/json
null

Diagnostics

Execute diagnostic checks on organization

This endpoint is the pulse-checker of organizational health in the HUMAN ecosystem. It orchestrates a series of diagnostic evaluations to determine the state of an organization's systems, applying auto-remediations where autonomy policies permit. It exists to ensure that AI and human interplays are seamlessly maintained, avoiding disruptions and ensuring safety.

Request Body schema: application/json
required
org_did
required
string

The DID of the organization for which diagnostics are to be performed.

Responses

Request samples

Content type
application/json

Running diagnostics for Acme Corp identified by its DID.

{
  • "org_did": "did:org:acme"
}

Response samples

Content type
application/json

Diagnostics for Acme Corp completed with some auto-remediations applied.

{
  • "run_id": "diag-run-123456",
  • "bucket": "degraded",
  • "checks": [
    ],
  • "autoRemediationApplied": true,
  • "autoRemediationsApplied": [
    ],
  • "escalationId": null
}

Retrieve diagnostics history for an organization

Explore the historical diagnostics events of your organization within the HUMAN platform. This endpoint empowers you to audit and trace past events, ensuring transparency and accountability in your AI orchestration. Utilize pagination to navigate large datasets effortlessly.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve Action Receipt Coverage Metric

Gauge the fidelity of human-AI interactions within your organization by examining the proportion of completed tasks that include an ActionReceipt. This metric helps ensure compliance with the ActionReceipt contract, targeting a coverage ratio of 90% or higher.

Responses

Response samples

Content type
application/json
{
  • "org_did": "did:example:123456789abcdefghi",
  • "window_days": 7,
  • "completed_invocations_sampled": 150,
  • "with_action_receipt": 135,
  • "receipt_coverage_ratio": 0.9,
  • "note": "Sampled from idempotency_keys (cached human.call responses). Target ≥ 0.9 per ActionReceipt contract."
}

Test connectivity for a specific connector

In the ever-evolving landscape of Human-AI orchestration, ensuring smooth communication channels is key. This endpoint lets you verify the live connectivity of a specified connector, using a quick probe, to ensure seamless task routing and skill tracking within the HUMAN ecosystem.

Request Body schema: application/json
required
probe
string

A test string sent to the connector to evaluate its responsiveness.

Responses

Request samples

Content type
application/json

Sending a simple probe to test connectivity.

{
  • "probe": "ping"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "connector_id": "acme123",
  • "latency_ms": 15
}

Health Check

Execute diagnostic checks on organization

This endpoint is the pulse-checker of organizational health in the HUMAN ecosystem. It orchestrates a series of diagnostic evaluations to determine the state of an organization's systems, applying auto-remediations where autonomy policies permit. It exists to ensure that AI and human interplays are seamlessly maintained, avoiding disruptions and ensuring safety.

Request Body schema: application/json
required
org_did
required
string

The DID of the organization for which diagnostics are to be performed.

Responses

Request samples

Content type
application/json

Running diagnostics for Acme Corp identified by its DID.

{
  • "org_did": "did:org:acme"
}

Response samples

Content type
application/json

Diagnostics for Acme Corp completed with some auto-remediations applied.

{
  • "run_id": "diag-run-123456",
  • "bucket": "degraded",
  • "checks": [
    ],
  • "autoRemediationApplied": true,
  • "autoRemediationsApplied": [
    ],
  • "escalationId": null
}

Agent Management

Retrieve and navigate agent records

Dive into the orchestration realm with the ability to list and paginate through HUMAN protocol agents. This endpoint empowers you to access detailed records of agents, filtering them by status and registration time, ensuring precise control over your data exploration.

Responses

Response samples

Content type
application/json

Retrieve a list of active agents with pagination.

{
  • "data": [
    ],
  • "limit": 2,
  • "next_cursor": "opaque_cursor_string"
}

Retrieve Scheduled Agent Tasks

Unlock a world of precision with the HUMAN platform's schedule viewer. This endpoint reveals the heartbeat of your automated operations, providing a clear view of when each agent is set to act next. It exists to empower proactive management and seamless orchestration of tasks. Hone your command over the Command Plane with this insightful glance into your agents' futures.

Responses

Response samples

Content type
application/json

A snapshot of Acme Corporation's agent schedules, offering a glimpse into their strategic task deployment.

{
  • "data": [
    ]
}

Pause an Agent's Active Schedule

In the dynamic world of Human-AI collaboration, there are moments when pausing an agent's schedule becomes essential. This endpoint empowers you to momentarily halt the operations of an agent, ensuring flexibility and control over automated processes. Whether it's a strategic pause for maintenance or oversight, this endpoint is your tool for agile orchestration.

Responses

Response samples

Content type
application/json

The agent's schedule is paused successfully.

{
  • "agentDid": "did:example:acme-agent-123",
  • "status": "paused"
}

Pause an agent's task execution

In the dynamic landscape of Human-AI orchestration, there are times when an agent's activities need to be paused for strategic realignment or resource management. This endpoint empowers administrators to pause an agent's task execution, ensuring that only relevant and prioritized tasks continue in the HUMAN ecosystem.

Responses

Response samples

Content type
application/json

An example where an agent with DID 'did:example:123456789' is paused successfully.

{
  • "agentDid": "did:example:123456789",
  • "status": "paused"
}

Update an Agent's Scheduled Tasks

Empower your AI agents by updating their task schedules with precision and ease. This endpoint allows you to set or clear a recurring task schedule using a familiar cron syntax, ensuring your agents operate at the right time, every time.

Request Body schema: application/json
required
schedule_cron
required
string or null

A valid cron expression for task scheduling. Set to null to clear existing schedule.

Responses

Request samples

Content type
application/json

Schedule the agent to run data processing every Monday at 3 AM.

{
  • "schedule_cron": "0 3 * * 1"
}

Response samples

Content type
application/json
null

Remove agent's scheduled tasks

In the world of ever-adaptive AI, agents must evolve. This endpoint clears the scheduled tasks for a given agent, ensuring they are primed for new missions. By removing outdated schedules, it empowers organizations to dynamically reassign resources as their strategies shift.

Responses

Response samples

Content type
application/json
{
  • "agent_did": "did:human:123456789abcdefghi",
  • "updated_at": "2023-10-05T14:48:00.000Z"
}

Resume a paused agent's operations

In the dynamic world of Human-AI collaboration, there's often a need to pause and resume activities as priorities shift. This endpoint breathes life back into a paused agent, enabling it to resume its tasks as part of a larger orchestration. By providing the agent's unique digital identity, you can seamlessly reactivate its capabilities within the HUMAN ecosystem.

Responses

Response samples

Content type
application/json
{
  • "agentDid": "did:example:1234567890",
  • "status": "active"
}

Override Agent Autonomy Settings

Empower your organization by customizing AI agent behaviors for specific tasks. This endpoint allows you to fine-tune the decision-making autonomy of an agent, ensuring it aligns with the unique operational needs of your organization.

Request Body schema: application/json
required
autonomy_level
required
string
Enum: "paranoid" "balanced" "aggressive"

The level of autonomy assigned to the agent.

org_did
required
string

The Decentralized Identifier (DID) of the organization setting the override.

reason
string

Optional rationale for setting or changing the autonomy level.

Responses

Request samples

Content type
application/json

Overrides the autonomy level of an agent handling invoice processing tasks to 'balanced' for the 'acme' organization.

{
  • "autonomy_level": "balanced",
  • "org_did": "org:acme",
  • "reason": "Ensuring proper oversight during financial audits."
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "org_did": "org:acme",
  • "agent_did": "agent:xyz123",
  • "autonomy_level": "balanced",
  • "set_by": "passport:alice",
  • "reason": "Ensuring proper oversight during financial audits.",
  • "updated_at": "2023-10-05T14:48:00.000Z"
}

Pause an agent's task acceptance

In the dynamic world of Human-AI orchestration, sometimes an agent needs a breather. This endpoint halts an agent's ability to accept new tasks, ensuring that our orchestration remains finely tuned and agile. Whether it's for routine maintenance or strategic planning, pausing gives you control over the flow of operations.

Request Body schema: application/json
required
reason
string

Optional explanation for pausing the agent

Responses

Request samples

Content type
application/json

Pausing the agent for routine system maintenance

{
  • "reason": "Scheduled maintenance"
}

Response samples

Content type
application/json
{
  • "agent": {
    }
}

Rollback an Agent to Previous Version

This endpoint allows you to roll back an agent to a previous version, providing a safety net for deployments. However, as of now, it's a blueprint for future capabilities, reminding us that the past isn't just a place—it’s a stepping stone.

Request Body schema: application/json
required
target_version
required
string

The version to which the agent should be rolled back, e.g., '1.2.2'.

reason
string

Optional reason for the rollback, providing context for future reference.

Responses

Request samples

Content type
application/json

This example demonstrates rolling back an agent to version 1.2.2 due to a critical bug discovered in the current version.

{
  • "target_version": "1.2.2",
  • "reason": "Critical bug in current version"
}

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Discover and propose agent tool schemas

Unveil the potential of your organization by discovering agent tools tailored to your specific capabilities. This endpoint serves as a bridge between your organizational needs and the world of Human-AI orchestration, suggesting agent tools that align with your capabilities, workforce, and marketplace opportunities.

Request Body schema: application/json
required
org_id
required
string

The organization's unique identifier

capabilities
Array of strings

List of capability URIs to match against agent tools

agent_ids
Array of strings

Specific agent IDs to filter results

include_workforce
boolean

Include workforce in the search results

include_marketplace
boolean

Include marketplace suggestions in the results

Responses

Request samples

Content type
application/json

Showcases a request from Acme Corp to find tools matching their capabilities

{
  • "org_id": "acme-corp",
  • "capabilities": [
    ],
  • "agent_ids": [ ],
  • "include_workforce": true,
  • "include_marketplace": true
}

Response samples

Content type
application/json

The response for a successful tool discovery request by Acme Corp

{
  • "tools": [
    ],
  • "workforce_workers": [
    ],
  • "marketplace_suggestions": [ ],
  • "capability_gaps": [ ],
  • "org_id": "acme-corp",
  • "tools_count": 1,
  • "workers_count": 1,
  • "suggestions_count": 0
}

Resume an Interrupted Agent Execution

In the fast-paced world of AI orchestration, interruptions can occur. This endpoint allows you to resume an agent’s workflow that was previously paused, ensuring seamless continuity in your operations. By providing a decision or input, you breathe life back into your processes, picking up precisely where they left off.

Request Body schema: application/json
required
resume_value
required
string

The decision or input required to resume the checkpoint.

Responses

Request samples

Content type
application/json

Resuming an invoice processing agent with the manager's approval decision.

{
  • "resume_value": "approved"
}

Response samples

Content type
application/json
{
  • "checkpoint_id": "chkpt_12345",
  • "status": "resumed",
  • "resumed_at": "2023-10-12T08:45:00Z"
}

Resources

Create a new resource in the system

Embark on a journey to enrich your digital ecosystem by creating a new resource within the HUMAN platform. This endpoint allows you to define and store a resource, ensuring it is uniquely identified and properly categorized. The process includes policy resolution to align with your organization's governance, making sure every resource fits seamlessly into your distributed ledger.

Request Body schema: application/json
required
uri
required
string

Canonical resource URI (must be unique)

kind
required
string

Resource kind (dot-separated namespace, e.g. core.email.message)

owner_did
required
string

Passport DID of the resource owner

schema_id
string or null

Schema ID this resource conforms to (e.g. core.email.message.v1)

metadata
object

Arbitrary metadata stored alongside the resource record

provenance_ref
string or null

Provenance chain reference ID

Responses

Request samples

Content type
application/json

An example to create a new email message resource for an organization.

{
  • "uri": "resource://core/email/msg_abc123",
  • "kind": "core.email.message",
  • "owner_did": "did:human:did_4f5e5e62",
  • "schema_id": "core.email.message.v1",
  • "metadata": {
    },
  • "provenance_ref": "prov_123456"
}

Response samples

Content type
application/json
null

Retrieve Active Resources List

Discover the available resources within the HUMAN platform, filtered by various criteria to suit your needs. This endpoint empowers you to efficiently navigate through a wealth of active resources, ensuring you have the right data at your fingertips.

Responses

Response samples

Content type
application/json

Returns a list of email message resources owned by Acme Corp, filtered by connector ID.

{
  • "data": [
    ],
  • "limit": 20,
  • "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyMy0xMC0wMVQxMjowMDowMFoifQ=="
}

Retrieve specific resource by ID or URI

Dive into the intricate world of resource management with this endpoint. Whether you possess a UUID or a URI, this call unravels the details of a singular resource, ensuring data integrity and precision in task orchestration through the HUMAN Protocol.

Responses

Response samples

Content type
application/json
{}

Modify a resource's core attributes

In a world where data evolves, updating a resource's fundamental attributes ensures it's always aligned with current realities. This endpoint allows you to modify key aspects of a resource, such as its kind, schema identification, metadata, and provenance reference, while maintaining a secure and immutable ownership structure.

Request Body schema: application/json
required
kind
string

A new classification for the resource

schema_id
string or null

Identifier for the resource's schema, if applicable

metadata
object

Additional data describing the resource

provenance_ref
string or null

Reference to the resource's provenance

Responses

Request samples

Content type
application/json

Changing the resource kind and adding metadata for better classification.

{
  • "kind": "core.invoice.document",
  • "metadata": {
    }
}

Response samples

Content type
application/json
null

Soft-delete a resource entry safely

In the intricate dance of data management, not all deletions are final. This endpoint offers a safeguard by soft-deleting a resource, marking it as inactive while keeping its historical footprint for audit trails. It's the digital equivalent of setting aside a book on a crowded shelf, knowing it can be revisited when needed.

Responses

Response samples

Content type
application/json

A resource identified by '12345' is successfully soft-deleted.

{
  • "resource_id": "12345",
  • "deleted": true,
  • "deleted_at": "2023-11-01T12:34:56Z"
}

Creation

Create a new resource in the system

Embark on a journey to enrich your digital ecosystem by creating a new resource within the HUMAN platform. This endpoint allows you to define and store a resource, ensuring it is uniquely identified and properly categorized. The process includes policy resolution to align with your organization's governance, making sure every resource fits seamlessly into your distributed ledger.

Request Body schema: application/json
required
uri
required
string

Canonical resource URI (must be unique)

kind
required
string

Resource kind (dot-separated namespace, e.g. core.email.message)

owner_did
required
string

Passport DID of the resource owner

schema_id
string or null

Schema ID this resource conforms to (e.g. core.email.message.v1)

metadata
object

Arbitrary metadata stored alongside the resource record

provenance_ref
string or null

Provenance chain reference ID

Responses

Request samples

Content type
application/json

An example to create a new email message resource for an organization.

{
  • "uri": "resource://core/email/msg_abc123",
  • "kind": "core.email.message",
  • "owner_did": "did:human:did_4f5e5e62",
  • "schema_id": "core.email.message.v1",
  • "metadata": {
    },
  • "provenance_ref": "prov_123456"
}

Response samples

Content type
application/json
null

Schemas

Retrieve effective schema for an organization

In the dynamic world of Human-AI orchestration, schemas define how data is structured and understood. This endpoint unveils the effective schema for a given organization and resource kind, ensuring the most precise and current configuration is applied. It caters to organizations like 'acme' that need tailored data handling based on their unique preferences and the latest standards.

Responses

Response samples

Content type
application/json
{
  • "schemaId": "schema:acme:core.email.message:v2",
  • "definition": {
    }
}

Register a new resource schema

In the dynamic realm of digital resources, schemas are the blueprints that guide interaction. This endpoint empowers organizations to register new schema versions, ensuring consistent understanding and validation across distributed systems. By enforcing authority rules, it safeguards namespace integrity, aligning with HUMAN's commitment to secure and trustworthy orchestration.

Request Body schema: application/json
required
kind
required
string

The resource kind identifier (e.g., core.email.message).

definition
required
object

A JSON Schema (draft 2020-12) detailing the structure of the resource kind.

authority_did
required
string

The Decentralized Identifier (DID) claiming authority over this kind's namespace.

created_by
required
string

DID of the entity (human or CI) registering the schema.

Responses

Request samples

Content type
application/json

Shows registration of a schema for email messages within the core namespace.

{
  • "kind": "core.email.message",
  • "definition": {
    },
  • "authority_did": "did:org:human",
  • "created_by": "did:agent:regina-phalange"
}

Response samples

Content type
application/json
{
  • "kind": "core.email.message",
  • "registered_at": "2023-10-01T12:00:00Z"
}

Retrieve registered schema list

Delve into the intricacies of schema management with the HUMAN platform. This endpoint unveils a comprehensive, cursor-paginated catalog of registered schemas, essential for orchestrating Human-AI interactions. Tailor your query with precision by utilizing filters for 'kind' and 'authority DID', ensuring you access exactly what you need.

Responses

Response samples

Content type
application/json

Fetches the first page of schemas, revealing the structure and metadata of each entry.

{
  • "data": [
    ],
  • "hasMore": false,
  • "limit": 20,
  • "cursorField": "created_at"
}

Retrieve an example schema payload

Dive into the world of schemas by fetching a sample payload that showcases its structure and usage. This endpoint is your gateway to creating realistic mock data, enhancing SDK documentation, and enriching your development playground with practical examples.

Responses

Response samples

Content type
application/json

An example payload for the core.email.message.v1 schema, perfect for testing email processing in your application.

{
  • "schema_id": "core.email.message.v1",
  • "kind": "message",
  • "version": "1.0",
  • "example": {
    }
}

Retrieve schema by unique identifier

Unlock the potential of structured data by accessing schemas through their unique identifiers. This endpoint is your gateway to understanding data models, enabling seamless integration and data orchestration across the HUMAN platform.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve all available schemas list

Dive into the intricacies of schema orchestration with this endpoint, which unveils a comprehensive list of schemas available within the HUMAN platform. Explore the structural backbone that powers the seamless Human-AI collaboration, providing you the keys to unlock deeper integrations.

Responses

Response samples

Content type
application/json

An example response showing the list of schema names available on the platform.

{
  • "items": [
    ],
  • "total": 3
}

Retrieve a Schema by Name

Uncover the intricacies of your data structures by retrieving a specific schema by its name. This endpoint empowers you to understand and validate the data models your HUMAN platform relies on, ensuring seamless integration and operation.

Responses

Response samples

Content type
application/json

Acme Corporation retrieves their invoice schema for validation.

{
  • "name": "invoiceSchema",
  • "schema": {
    }
}

Configuration

Retrieve effective schema for an organization

In the dynamic world of Human-AI orchestration, schemas define how data is structured and understood. This endpoint unveils the effective schema for a given organization and resource kind, ensuring the most precise and current configuration is applied. It caters to organizations like 'acme' that need tailored data handling based on their unique preferences and the latest standards.

Responses

Response samples

Content type
application/json
{
  • "schemaId": "schema:acme:core.email.message:v2",
  • "definition": {
    }
}

Remove organization schema preference

In the realm of digital orchestration, it's crucial to manage the schemas that guide your organization. This endpoint allows you to delete an existing schema preference by specifying its unique organization DID and kind pattern. Once removed, the system will revert to the latest default schema, ensuring seamless continuity.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Configure Organization Autonomy Profile

Elevate your organization's decision-making capabilities by setting an autonomy profile that aligns with your operational strategy. This endpoint allows you to define how autonomously your systems should operate, striking a balance between human oversight and AI efficiency. Choose from 'Paranoid', 'Balanced', or 'Aggressive' profiles to best suit your organization's needs.

Request Body schema: application/json
required
autonomy_profile
required
string
Enum: "paranoid" "balanced" "aggressive"

Specifies the level of autonomy granted to the organization.

Responses

Request samples

Content type
application/json

Setting the autonomy profile to 'Balanced' for an organization.

{
  • "autonomy_profile": "balanced"
}

Response samples

Content type
application/json

Organization's autonomy profile updated to 'Balanced'.

{
  • "org_did": "did:example:123456",
  • "autonomy_profile": "balanced",
  • "settings": {
    }
}

Update workforce routing configuration

Fine-tune your organization's task routing by configuring workforce settings. This endpoint ensures that tasks are directed efficiently to human and AI agents using up-to-date configurations, providing a seamless orchestration experience.

Request Body schema: application/json
required
required
object

Dynamic routing configuration settings

Responses

Request samples

Content type
application/json

Configure routing for Acme's invoice processing tasks to ensure tasks are managed efficiently across teams.

{
  • "config": {
    }
}

Response samples

Content type
application/json
null

Data Management

Retrieve registered schema list

Delve into the intricacies of schema management with the HUMAN platform. This endpoint unveils a comprehensive, cursor-paginated catalog of registered schemas, essential for orchestrating Human-AI interactions. Tailor your query with precision by utilizing filters for 'kind' and 'authority DID', ensuring you access exactly what you need.

Responses

Response samples

Content type
application/json

Fetches the first page of schemas, revealing the structure and metadata of each entry.

{
  • "data": [
    ],
  • "hasMore": false,
  • "limit": 20,
  • "cursorField": "created_at"
}

Soft-delete a resource entry safely

In the intricate dance of data management, not all deletions are final. This endpoint offers a safeguard by soft-deleting a resource, marking it as inactive while keeping its historical footprint for audit trails. It's the digital equivalent of setting aside a book on a crowded shelf, knowing it can be revisited when needed.

Responses

Response samples

Content type
application/json

A resource identified by '12345' is successfully soft-deleted.

{
  • "resource_id": "12345",
  • "deleted": true,
  • "deleted_at": "2023-11-01T12:34:56Z"
}

Remove a document from the vault

In the HUMAN ecosystem, deleting a document is akin to erasing a chapter from a ledger. This endpoint allows users to surgically remove artifacts from their vault, ensuring that only the most relevant data persists, thus maintaining a pristine and efficient data environment.

Responses

Response samples

Content type
application/json

Illustrates a successful delete operation where the document is removed from the vault.

null

Retrieve pending disclosures for a Passport

Explore the intricacies of managing digital identity by retrieving pending disclosure requests linked to a specific Passport. This endpoint allows users to track and manage requests, ensuring transparency and control over their personal data.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

OrgSchemaPrefs

Retrieve organizational schema preferences

Dive into the world of schemas where each organization defines its unique structure. This endpoint allows you to explore and manage how an organization's data is expected to be shaped, enabling precise data orchestration and ensuring compatibility. By mapping data kinds to preferred schemas, organizations can maintain consistency and control over their data landscape.

Responses

Response samples

Content type
application/json

A snapshot of the schema preferences for the 'acme' organization.

{
  • "data": [
    ],
  • "limit": 20,
  • "cursorField": "created_at",
  • "hasMore": true
}

Upsert organization schema preferences

In the dynamic world of schema management, this endpoint empowers organizations to define and refine their schema preferences with precision. Whether it's a new schema pattern or an update to an existing one, this ensures that the most relevant schema is always at the forefront, aiding efficient task routing and AI interactions.

Request Body schema: application/json
required
org_did
required
string

A unique identifier for the organization in the form of a DID.

kind_pattern
required
string

A kind or glob pattern for which the schema preference is being set.

preferred_schema_id
required
string

The identifier of the schema that the organization prefers.

Responses

Request samples

Content type
application/json

This example demonstrates setting a preferred schema for health-related data within the Acme organization.

{
  • "org_did": "did:org:acme",
  • "kind_pattern": "core.health.*",
  • "preferred_schema_id": "core.health.ct_scan.v1"
}

Response samples

Content type
application/json
{
  • "org_did": "did:org:acme",
  • "kind_pattern": "core.health.*",
  • "preferred_schema_id": "core.health.ct_scan.v1",
  • "created_at": "2023-10-01T12:00:00Z"
}

Remove organization schema preference

In the realm of digital orchestration, it's crucial to manage the schemas that guide your organization. This endpoint allows you to delete an existing schema preference by specifying its unique organization DID and kind pattern. Once removed, the system will revert to the latest default schema, ensuring seamless continuity.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Health

Check platform readiness and component health

The GET /ready endpoint provides a vital snapshot of the HUMAN platform's operational status, ensuring that both the database and Redis components are functioning correctly. This health check empowers system administrators to maintain a seamless orchestration of Human-AI tasks by proactively identifying and addressing potential service disruptions.

Responses

Response samples

Content type
application/json

The system is fully operational, with all components connected.

{
  • "ready": true,
  • "database": "connected",
  • "redis": "connected",
  • "timestamp": "2023-03-15T12:45:30.000Z"
}

Permissions

Retrieve Grants for Authenticated User

Explore the intricate web of permissions with the HUMAN platform by listing all grants where you are the granter. This endpoint unifies both delegation and capability grants into a single view, empowering you to understand and manage the permissions you have bestowed.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "nextCursor": "cursor_string"
}

Grants

Retrieve Detailed Grant Information

Uncover the full potential of your grant by retrieving detailed information including scopes, constraints, and usage history. This endpoint empowers the granter to manage and review their own grants, ensuring security and transparency in capabilities sharing.

Responses

Response samples

Content type
application/json

An example response for retrieving a grant used by the Acme organization.

{
  • "grant_id": "grant123",
  • "scopes": [
    ],
  • "constraints": {
    },
  • "last_used_at": "2023-10-21T15:23:45Z"
}

Expire an active delegation grant early

In the intricate world of Human-AI collaboration, timing is everything. This endpoint allows you to shorten the expiry of an active delegation grant, ensuring that permissions are curtailed as needed. By empowering users to manage time-sensitive access, we enhance security and control.

Request Body schema: application/json
required
expires_at
required
string <date-time>

The new expiry date, which must be a valid ISO 8601 timestamp and cannot extend the current expiry.

Responses

Request samples

Content type
application/json

This example shows how to shorten the expiry of a grant to a specific future date.

{
  • "expires_at": "2023-12-31T23:59:59Z"
}

Response samples

Content type
application/json
null

Retrieve Active Audit Grants

Discover the active grants for an organization, granting you insights into what capabilities are being utilized and by whom. This endpoint helps maintain transparency and accountability within the HUMAN network, ensuring all actions are traceable and verifiable.

Responses

Response samples

Content type
application/json

A list of active audit grants for organization 'acme'.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at",
  • "hasMore": false,
  • "redacted_count": 0,
  • "redacted_reason": ""
}

ServiceAccount

Create a new service account

This endpoint empowers organizations to create service accounts linked to their digital identity, enhancing automated interactions with HUMAN's ecosystem. Service accounts facilitate automated access to resources, allowing seamless integration while maintaining security through scoped permissions and IP allowlists.

Request Body schema: application/json
required
name
required
string

A descriptive name for the service account.

description
string

Optional detailed information about the service account's purpose.

scopes
required
Array of strings

An array of capability URIs defining the service account's permissions.

ip_allowlist
Array of strings <ipv4> [ items <ipv4 > ]

A list of IP addresses allowed to use this service account.

owner_passport_did
string

The DID of the owner passport, starting with 'did:human:'.

Responses

Request samples

Content type
application/json

This example demonstrates setting up a service account for 'acme' organization to automate invoice processing.

{
  • "name": "Invoice Processor",
  • "description": "Handles automated invoice processing tasks.",
  • "scopes": [
    ],
  • "ip_allowlist": [
    ],
  • "owner_passport_did": "did:human:org:acme"
}

Response samples

Content type
application/json

A successful response after creating a service account for 'acme'.

{
  • "service_account_id": "hsa12345",
  • "api_key": "HSK_live_4bGZ2k...",
  • "name": "Invoice Processor",
  • "scopes": [
    ],
  • "ip_allowlist": [
    ],
  • "created_at": "2023-10-01T08:00:00Z"
}

Application

Register a new application with a Passport

Embark on a journey to integrate your application into the HUMAN ecosystem by registering it with a unique Passport. This endpoint establishes your application's identity, enabling it to interact securely and efficiently through HUMAN's protocol.

Request Body schema: application/json
required
app_name
required
string

The name of your application

app_type
required
string
Enum: "web" "native" "spa"

The type of application, guiding security strategies

redirect_uris
required
Array of strings <uri> [ items <uri > ]
scopes
required
Array of strings

Responses

Request samples

Content type
application/json

This example registers a web application named 'Invoicer' for managing company invoices.

{}

Response samples

Content type
application/json
null

OAuth

Authorize client with OAuth protocol

Initiate an OAuth authorization flow for a client application using the HUMAN Passport. This endpoint ensures that only verified applications can request access, protecting users and maintaining system integrity.

Responses

Response samples

Authorize and Consent OAuth Requests

Facilitates user consent for OAuth authorization by securely handling the exchange of authorization codes. This endpoint ensures that users' cryptographic identities and delegated capabilities are respected, maintaining a seamless and secure user experience.

Request Body schema: application/json
required
request_id
required
string

A unique identifier for the OAuth authorization request.

Responses

Request samples

Content type
application/json

A typical request for authorizing an OAuth process.

{
  • "request_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json

Redirect URL with the granted authorization code.

{}

Exchange authorization code for access token

Unlock the potential of your applications by exchanging an authorization code for an access token. This endpoint safeguards the integrity of your interactions by ensuring strict adherence to OAuth standards, empowering developers to harness secure and seamless user authentication.

Request Body schema: application/json
required
grant_type
required
string
Value: "authorization_code"

The type of grant being used. Must be 'authorization_code'.

code
required
string

The authorization code received from the authorization server.

redirect_uri
required
string <uri>

The redirect URI used in the authorization request.

client_id
required
string

The client identifier issued to the client during the registration process.

client_secret
string

The client secret issued to the client during the registration process.

code_verifier
required
string >= 43 characters

The code verifier for PKCE validation.

Responses

Request samples

Content type
application/json

Demonstrates a typical request to exchange an authorization code for an access token.

{
  • "grant_type": "authorization_code",
  • "code": "abc123xyz",
  • "redirect_uri": "https://example.com/callback",
  • "client_id": "acme-client-id",
  • "client_secret": "acme-client-secret",
  • "code_verifier": "verifier1234567890abcdefghijklmnopqrstuvwxyzABCDEF"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "scope": "read:invoices write:invoices"
}

Verification

Verify the authenticity of a Passport credential

Dive into the heart of identity verification with this endpoint, where credentials are scrutinized to ensure trustworthiness. In a world where digital identities are pivotal, knowing the truth behind a credential is paramount. This service verifies the integrity and validity of a Passport credential, giving organizations the confidence they need in their digital interactions.

Request Body schema: application/json
required
One of
credential_id
required
string

The unique identifier for the credential

Responses

Request samples

Content type
application/json

An example of verifying a credential using the modern field name

{
  • "credential_id": "cred-12345"
}

Response samples

Content type
application/json
null

Request Passport Disclosure

Initiate a request for specific identity disclosures tied to a human DID. This endpoint empowers applications to verify identity attributes while maintaining control over privacy and consent. It's a gateway to a world where digital trust is built on human identity, not just numbers.

Request Body schema: application/json
required
subject_did
required
string

The DID of the human whose attributes are being requested. Must start with 'did:human:'.

requested_attributes
required
Array of strings

Array of attribute names to disclose.

purpose
string

The purpose of the disclosure request.

expires_in
integer

The time in seconds until the request expires, between 60 and 604800 (7 days).

Responses

Request samples

Content type
application/json

A request to obtain the email and phone number of a user for account verification purposes.

{
  • "subject_did": "did:human:123456789abcdefghi",
  • "requested_attributes": [
    ],
  • "purpose": "Account verification",
  • "expires_in": 3600
}

Response samples

Content type
application/json
{}

Retrieve Passport's Verification Status

Explore the journey of a passport as it climbs the Validity Ladder, unlocking new capabilities at each tier. This endpoint reveals the layers of verification and identity tiers achieved by a passport, enabling clients to guide users through potential upgrades.

Responses

Response samples

Content type
application/json

The verification and identity status for Acme Corp's passport, highlighting unlocked and gated capabilities.

{
  • "did": "did:human:acme12345",
  • "verification_tier": 2,
  • "identity_tier": 1,
  • "layers": {
    },
  • "identity_tiers": {
    },
  • "capabilities_unlocked": [
    ],
  • "capabilities_gated": [
    ]
}

Verify email and complete passport link

This endpoint breathes life into the digital identity by verifying an email using a 6-digit code. It completes the vital connection between a passport and an organization, triggering an attestation that signals a trustworthy relationship. No additional authentication is needed beyond the code, making the process seamless and efficient.

Request Body schema: application/json
required
code
required
string

A 6-digit verification code sent to the user's email.

Responses

Request samples

Content type
application/json

Submits a 6-digit code to verify and link the email.

{
  • "code": "123456"
}

Response samples

Content type
application/json
null

Initiate domain verification for an organization

Verify an organization's domain as part of its cryptographic identity within the HUMAN Protocol. This process ensures the authenticity of the domain ownership, enhancing trust and security in AI-human task orchestration.

Request Body schema: application/json
required
One of
org_did
required
string^did:org:.*$

The Decentralized Identifier (DID) of the organization

domain
required
string

The domain name to be verified

Responses

Request samples

Content type
application/json

Initiating domain verification for Acme Corp.

{
  • "org_did": "did:org:acme",
  • "domain": "acmecorp.com"
}

Response samples

Content type
application/json
null

Verify biometric identity via webhook

This endpoint is the critical touchpoint where human and machine meet to ensure identity integrity. It enables seamless biometric verification, elevating the user's verification and identity tier while safeguarding against fraud through cryptographic checks.

Responses

Response samples

Content type
application/json

The biometric verification was successful, advancing verification and identity tiers.

{
  • "received": true,
  • "status": "clear"
}

Submit a signed vouch for identity

In a digital world, trust is invaluable. This endpoint allows trusted agents to vouch for a cryptographic identity, contributing to its social verification. Achieving a certain number of vouches can elevate the identity's verification tier, enhancing its credibility within the HUMAN ecosystem.

Request Body schema: application/json
required
voucher_did
required
string

Decentralized Identifier (DID) of the voucher

statement
required
string

A statement explaining the reason for the vouch

confidence
required
string
Enum: "high" "medium" "low"

Level of confidence in the vouch

relationship
required
string
Enum: "colleague" "friend" "family" "other"

The type of relationship with the subject

met_since
string <date-time>

Date since the voucher knows the subject

signature
required
string

Ed25519 signature of the vouch statement

timestamp
string <date-time>

Timestamp of when the vouch was created

Responses

Request samples

Content type
application/json

A vouch from a colleague with high confidence.

{
  • "voucher_did": "did:human:987654321abcdef",
  • "statement": "I have collaborated with them on multiple successful projects.",
  • "confidence": "high",
  • "relationship": "colleague",
  • "met_since": "2015-03-15T00:00:00Z",
  • "signature": "base64urlencodedstring",
  • "timestamp": "2023-10-10T14:48:00Z"
}

Response samples

Content type
application/json

A successful vouch submission that advanced the subject's verification tier.

{
  • "vouch_id": "pvo1234567890abcdef",
  • "active_vouches": 3,
  • "tier_3_achieved": true
}

Verify Verifiable Credential for Passport

Elevate your digital identity by submitting a Verifiable Credential, pushing your identity tier to 3. This endpoint verifies credentials from trusted issuers, ensuring your identity is both secure and recognized. An advanced identity tier opens doors to more opportunities within the HUMAN ecosystem.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json

A credential submission for an identity verification.

{
  • "credential": {
    }
}

Response samples

Content type
application/json
{
  • "identity_tier": 3,
  • "credential_id": "cred-12345"
}

Initiate Proof of Personhood verification

Embark on a journey to establish the authenticity of an individual's identity through the Proof of Personhood process. This operation ensures that the passport in question truly belongs to a human, reinforcing trust in the HUMAN network.

Responses

Response samples

Content type
application/json

Initiating a session for Proof of Personhood verification.

{}

Verify Proof of Personhood via Webhook

This endpoint receives and processes the Proof of Personhood (PoP) verification from a provider. By advancing the verification tier to 4, it ensures the cryptographic identity represented by a Passport is uniquely tied to a human, preventing duplicate identities in the HUMAN ecosystem.

Request Body schema: application/json
required
nullifierHash
required
string

Unique hash representing the verified individual.

provider
required
string

The PoP provider processing the request.

signature
string

Signature verifying the authenticity of the webhook call.

Responses

Request samples

Content type
application/json

A typical PoP verification result from the provider.

{
  • "nullifierHash": "abc123xyz456",
  • "provider": "trusted_pop_provider",
  • "signature": "signed_payload_hash"
}

Response samples

Content type
application/json
{
  • "received": true,
  • "status": "verified",
  • "verification_tier": 4
}

Verify Capability Proofs for Authorization

In the HUMAN protocol, verifying capability proofs is essential for ensuring that agents possess the necessary skills to execute a task. This endpoint authenticates the validity of a submitted proof, safeguarding against expired, inactive, or mismatched data, and ensuring trust in the orchestration process.

Request Body schema: application/json
required
proof_id
required
string

The unique identifier for the capability proof.

proof_data
required
string

The cryptographic data associated with the capability proof.

Responses

Request samples

Content type
application/json

Validates that an agent from 'acme' organization has the verified capability to process invoices.

{
  • "proof_id": "proof-12345",
  • "proof_data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
null

Verify capabilities within the graph

In the realm of human-AI collaboration, knowing who can do what is crucial. This endpoint verifies whether a specific capability exists within an agent's graph, ensuring tasks are routed to the right human or AI. By validating capabilities, we maintain trust and accuracy in AI-driven workflows.

Request Body schema: application/json
required
agentId
required
string

The unique identifier for the agent whose capabilities are being verified.

capabilityId
required
string

The unique identifier of the capability to be verified.

Responses

Request samples

Content type
application/json

This example checks if the 'data-processing' capability exists for agent 'agent-123'.

{
  • "agentId": "agent-123",
  • "capabilityId": "data-processing"
}

Response samples

Content type
application/json
null

Credentials

Revoke a specific passport credential

This endpoint allows the issuing passport to revoke a credential, reflecting changes in a user's capability graph. By revoking a credential, you ensure the integrity and accuracy of the distributed ledger, protecting the ecosystem from outdated or incorrect data.

Request Body schema: application/json
required
One of
effective_date
required
string <date-time>

The ISO 8601 date-time when the revocation should take effect.

Responses

Request samples

Content type
application/json

Revoke a credential starting from January 1, 2024.

{
  • "effective_date": "2024-01-01T00:00:00Z"
}

Response samples

Content type
application/json
null

Retrieve Verified Credentials for Passport

Delve into the rich tapestry of your digital identity by retrieving your verified credentials. This endpoint empowers you to securely access and manage the credentials tied to your Passport, ensuring that only you hold the key to your identity's narrative.

Responses

Response samples

Content type
application/json

Shows a successful retrieval of credentials for a user's Passport.

{
  • "credentials": [
    ],
  • "cursor": "opaque-cursor-string",
  • "hasMore": false,
  • "total": 1
}

Create a Client-Signed Credential

This endpoint allows an authenticated issuer to create a client-signed credential within the HUMAN network. By leveraging cryptographic proofs, it ensures the integrity and authenticity of issued credentials, advancing trust in decentralized identity management.

Request Body schema: application/json
required
One of
subject_did
required
string^did:human:.*
issuer_did
required
string^did:human:.*
type
Array of strings
claims
required
object
issued_at
required
string <date-time>
expiration_date
string <date-time>
signature
required
string
signing_key_purpose
string
Enum: "attest" "auth"

Responses

Request samples

Content type
application/json

Example of issuing a credential for a subject with specific claims.

{
  • "subject_did": "did:human:example123",
  • "issuer_did": "did:human:issuer456",
  • "type": [
    ],
  • "claims": {
    },
  • "issued_at": "2023-10-01T12:00:00Z",
  • "expiration_date": "2024-10-01T12:00:00Z",
  • "signature": "base64encodedsignature==",
  • "signing_key_purpose": "attest"
}

Response samples

Content type
application/json

A credential issued for a software engineer at Acme Corp.

{
  • "credential_id": "cred-abcdef123456",
  • "type": [
    ],
  • "issued_at": "2023-10-01T12:00:00Z",
  • "proof": {
    },
  • "ledger_anchor": {
    }
}

Store connector credentials securely

This endpoint empowers organizations by securely storing credentials for connectors, ensuring proper authentication and authorization. It is crucial for maintaining seamless integration and automated workflows across varied systems, embodying the dynamic nature of modern orchestration.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve Decrypted Connector Credentials

Unlock the power of seamless integration by retrieving decrypted credentials for a specified connector. This endpoint ensures that entities can securely access credentials, enabling the orchestration of tasks without compromising security. By tailoring retrieval to specific scopes, it maximizes flexibility while maintaining stringent control over sensitive data.

Responses

Response samples

Content type
application/json

A successful response showing decrypted credentials for the 'acme' organization connector.

{
  • "credential": {
    },
  • "decrypted_credentials": {
    }
}

Retrieve Credential List for Connector

Unearth the hidden troves of credentials tied to a specific connector, a crucial step in managing your entity's digital keys. This endpoint allows the secure listing of credentials, providing transparency and control over who can access and perform operations within your system.

Responses

Response samples

Content type
application/json

An example of credentials retrieved for a specific connector.

{
  • "credentials": [
    ],
  • "count": 1
}

Retrieve 30-day credential usage statistics

Unlock insights into your system's performance by examining detailed 30-day usage statistics for a specific credential. This endpoint provides a comprehensive overview, including invocation counts, success and failure rates, and cost metrics, empowering you to optimize resource allocation and enhance operational efficiency.

Responses

Response samples

Content type
application/json

A snapshot of how Acme Corp's credential is performing over the last month

{
  • "credential_id": "cred-1234",
  • "period": "30_days",
  • "total_invocations": 1500,
  • "successful_invocations": 1450,
  • "failed_invocations": 50,
  • "total_cost_usd": 123.45,
  • "total_tokens_used": 7500,
  • "avg_duration_ms": 235.67,
  • "last_used_at": "2023-10-01T12:34:56Z",
  • "most_used_operation": "processInvoice"
}

Retrieve credential cache statistics

Peel back the curtain on the performance of your credential caching system with this endpoint. Designed for system administrators, it provides a snapshot of cache efficiency, offering insights into hits, misses, and evictions. This data is crucial for optimizing the performance and reliability of your organization's credential handling.

Responses

Response samples

Content type
application/json

An example response showing typical cache statistics.

{
  • "hits": 1200,
  • "misses": 300,
  • "evictions": 50,
  • "size": 500,
  • "hit_rate": 0.8,
  • "hit_rate_percent": "80.00%"
}

Consents

Retrieve Passport Consent Records

Dive into the chronicles of your digital identity by exploring the consents associated with your Passport. This endpoint empowers you to audit the permissions granted to various agents, ensuring transparency and control over your digital footprint.

Responses

Response samples

Content type
application/json
{
  • "consents": [
    ],
  • "limit": 10,
  • "cursor": "eyJncmFudGVkX2F0IjogIjIwMjMtMTAtMDFUMTA6MDA6MDBaIiwgImNvbnNlbnRfaWQiOiAiYzFmM2VlYjQtMTJhZi00ZTlkLWE2NTQtNGYwYTdiNGMzYzhkIn0=",
  • "total": 1
}

Consent Management

Revoke a Passport Consent

When trust is no longer warranted, revoke a consent tied to a Passport. This endpoint ensures control over shared data and maintains user sovereignty.

Request Body schema: application/json
required
One of
revocation_reason
required
string

The reason for revocation.

Responses

Request samples

Content type
application/json

Shows how to revoke consent when data policy updates require it.

{
  • "revocation_reason": "Data policy changes require consent review."
}

Response samples

Content type
application/json
{
  • "consent_id": "consent-12345",
  • "status": "revoked",
  • "revoked_at": "2023-10-21T14:48:00.000Z"
}

Webhooks

Register a webhook for passport events

In a world where human and AI collaboration is key, webhooks allow organizations to seamlessly integrate and respond to passport events in real-time. This endpoint empowers you to subscribe to specific events, ensuring your systems are always in sync with the latest happenings.

Request Body schema: application/json
required
url
required
string

Target URL for the webhook (must use http or https).

secret
required
string

Secret for HMAC signing of webhook payloads (min 8 characters).

events
required
Array of strings

Array of passport event names to subscribe to.

Responses

Request samples

Content type
application/json

Setting up a webhook for Acme Corporation to listen to passport creation and update events.

{}

Response samples

Content type
application/json
{
  • "webhook_id": "webhook-1234",
  • "subscription_ids": [
    ],
  • "url": "https://webhooks.acme.com/passport",
  • "events": [
    ],
  • "signing_secret_stored": true
}

Subscribe to Webhook Events for Your Organization

Imagine receiving only the events that matter most to your organization, seamlessly and securely. This endpoint allows you to subscribe to webhook events, ensuring your systems are always in sync with the latest updates from the HUMAN platform. It's designed for organizations looking to automate and streamline their workflows with precision.

Request Body schema: application/json
required
event_pattern
required
string

The pattern of events to subscribe to, using dot-notation.

target_url
required
string <uri>

The destination URL where events will be delivered.

signing_secret
string

Optional secret for signing webhook requests.

source_filter
string

Optional filter for the event source.

observability_profile
string

Profile ID for observability settings.

metadata
object

Additional metadata for the subscription.

audience
string
Enum: "tenant_safe" "platform_internal"

Defines who the subscription is intended for.

Responses

Request samples

Content type
application/json

Acme Corp subscribing to all billing invoice events.

{
  • "event_pattern": "billing.invoice.*",
  • "target_url": "https://webhooks.acme.com/events",
  • "signing_secret": "supersecret",
  • "metadata": {
    },
  • "audience": "tenant_safe"
}

Response samples

Content type
application/json

Response when Acme Corp successfully subscribes to webhook events.

{
  • "subscription_id": "sub-12345",
  • "event_pattern": "billing.invoice.*",
  • "target_url": "https://webhooks.acme.com/events",
  • "signing_secret_provided": true,
  • "metadata": {
    }
}

Retrieve active webhook subscriptions

This endpoint lets you explore the landscape of webhook subscriptions tied to your organization. By calling it, you can discover which events you're tracking in real-time, ensuring your applications remain in sync with the heartbeat of your business.

Responses

Response samples

Content type
application/json

A response showing active webhook subscriptions for a specific organization.

{
  • "data": [
    ],
  • "hasMore": false,
  • "limit": 2,
  • "cursor": "opaqueCursor123"
}

Retrieve webhook subscription details

Unlock the secrets of your organization's data flow by retrieving the details of a webhook subscription. This endpoint illuminates the path for authorized users to inspect the subscriptions tied to their cryptographic identity, ensuring data harmony between systems.

Responses

Response samples

Content type
application/json

Fetching details of a webhook subscription for Acme Corporation.

{}

Deactivate a webhook subscription

Effortlessly manage webhook subscriptions by deactivating them without losing valuable delivery history. This endpoint allows organizations to gracefully retire subscriptions, ensuring continuity and integrity of past interactions.

Responses

Response samples

Content type
application/json

An example of successfully deactivating a subscription for an organization.

{
  • "subscription_id": "sub-12345",
  • "active": false,
  • "deactivated_at": "2023-10-01T12:34:56Z"
}

Process incoming webhooks for extensions

This endpoint orchestrates the reception of webhooks from external services for specific extensions, ensuring seamless integration and task automation. It empowers developers to extend the HUMAN platform by acknowledging incoming data from third-party sources, facilitating a real-time, responsive ecosystem.

Request Body schema: application/json
required
event
required
string

The type of event triggering the webhook

object

The event-specific data payload

Responses

Request samples

Content type
application/json

A webhook event triggered by an external service

{
  • "event": "invoice.processed",
  • "data": {
    }
}

Response samples

Content type
application/json
null

Retrieve webhook delivery history

This endpoint unveils the rich tapestry of webhook deliveries for a specific subscription, providing insight into the lifecycle and status of each delivery attempt. Whether you're troubleshooting a missing event or analyzing delivery performance, this endpoint offers a transparent view into your webhook ecosystem.

Responses

Response samples

Content type
application/json

Retrieve deliveries for subscription 'sub_1234' with a comprehensive view of each delivery's status.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursor": "opaque_cursor_string",
  • "hasMore": false,
  • "queue_summary": {
    }
}

Retrieve specific webhook delivery details

Uncover the story behind your webhook delivery attempts by retrieving detailed information on a specific delivery using its unique ID. This endpoint allows organizations to audit their webhook deliveries, track attempts, and gain insights into potential issues.

Responses

Response samples

Content type
application/json

Details of a successful webhook delivery retrieval for organization 'acme'.

{
  • "deliveryId": "del_123456",
  • "subscriptionId": "sub_987654",
  • "eventId": "evt_13579",
  • "status": "delivered",
  • "targetUrl": "https://webhooks.acme.com/events",
  • "attemptCount": 1,
  • "maxAttempts": 3,
  • "nextAttemptAt": null,
  • "lastHttpStatus": 200,
  • "lastResponseBody": "OK",
  • "lastError": null,
  • "lastAttemptedAt": "2023-10-12T14:48:00Z",
  • "idempotencyKey": "idemp_2468",
  • "createdAt": "2023-10-10T09:00:00Z",
  • "updatedAt": "2023-10-12T14:48:00Z"
}

Retry delivery of failed webhooks

In the ever-evolving landscape of automated tasks, not everything goes as planned. This endpoint allows you to breathe life back into previously failed or 'dead' webhook deliveries, setting them on the path to success once more. It's a second chance for your integrations to communicate effectively.

Responses

Response samples

Content type
application/json

Shows a webhook delivery that has been successfully queued for a retry.

{
  • "delivery_id": "123e4567-e89b-12d3-a456-426614174000",
  • "status": "pending",
  • "redelivered_at": "2023-10-01T12:00:00Z"
}

Initiate a Webhook Subscription Test

This endpoint allows organizations to queue a synthetic test delivery for their webhook subscriptions. It's a powerful tool to ensure that your webhook configurations are correctly set up and ready to receive events. By simulating a webhook event, organizations can verify the integrity and responsiveness of their integrations.

Request Body schema: application/json
required
orgDid
required
string

Decentralized identifier for the organization initiating the test

Responses

Request samples

Content type
application/json

Example of a request to initiate a test delivery for webhook subscription with a valid org DID.

{
  • "orgDid": "did:example:123456789abcdefghi"
}

Response samples

Content type
application/json
null

Installation

Install an Ontology Package for Organization

This endpoint allows organizations to seamlessly install or update ontology packages within the HUMAN platform. By ensuring only published package versions are used, it maintains integrity and provides a record of installation activities, helping organizations stay on top of their capabilities.

Request Body schema: application/json
required
org_id
required
string

Unique identifier for the organization.

org_slug
required
string

Slug name for the organization.

package_version
required
string

The version of the ontology package to install, must be a semantic version.

payment_id
string

Optional payment identifier if payment processing is involved.

Responses

Request samples

Content type
application/json

This example demonstrates installing version 1.2.3 of a package for ACME Corporation.

{
  • "org_id": "org-12345",
  • "org_slug": "acme-corp",
  • "package_version": "1.2.3",
  • "payment_id": "pay-6789"
}

Response samples

Content type
application/json
{
  • "installation_id": "ont_inst_001",
  • "package_id": "pkg-123",
  • "package_version": "1.2.3",
  • "org_id": "org-12345",
  • "org_slug": "acme-corp",
  • "status": "active",
  • "installed_by": "user-789",
  • "installed_at": "2023-10-01T12:00:00Z",
  • "updated": true
}

Install Marketplace Asset to Organization

Seamlessly integrate pre-approved marketplace assets into your organization using the HUMAN platform. This endpoint facilitates the installation process by ensuring assets meet organizational policies and trust tiers, empowering organizations to expand their capabilities securely.

Request Body schema: application/json
required
asset_id
required
string

Unique identifier for the asset to be installed.

org_did
required
string

Decentralized identifier (DID) of the organization.

object

Configuration overrides specific to the asset installation.

preset
string
Default: "safe"

Preset configuration for the asset, defaults to 'safe'.

custom_scopes
Array of strings

Custom scopes required for asset installation.

Responses

Request samples

Content type
application/json

Install a simple extension asset to an organization.

{
  • "asset_id": "asset-12345",
  • "org_did": "did:org:acme",
  • "config_overrides": { },
  • "preset": "safe"
}

Response samples

Content type
application/json
{
  • "result": "Asset 'asset-12345' successfully installed for organization 'did:org:acme'."
}

Enrollments

Retrieve learner enrollments with filters

Dive into the world of learning by exploring enrollments filtered by status or learner. This endpoint empowers organizations to seamlessly track and manage educational journeys, ensuring learners are on the right path to success.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "enrolled_at",
  • "hasMore": false
}

Enrollment

Enroll Learner in Academy Course

Embark on a journey of knowledge with the HUMAN platform's Academy. This endpoint allows learners to enroll in courses, leveraging their digital identity. Whether you're a seasoned professional or a curious novice, track your progress and elevate your skills seamlessly.

Request Body schema: application/json
required
did
string

Decentralized Identifier for the learner.

learner_id
string

Unique identifier of the learner.

passport_id
string

Passport ID representing the learner's identity.

course_id
required
string

The course identifier in which the learner wishes to enroll.

Responses

Request samples

Content type
application/json

A learner enrolls using their Decentralized Identifier.

{
  • "did": "did:human:12345",
  • "course_id": "course-101"
}

Response samples

Content type
application/json
null

Complete an Enrollment and Anchor to Ledger

This endpoint finalizes a learner's enrollment by marking it as complete and issuing a cryptographic certification on the Distributed Ledger. This ensures an immutable proof of completion, paving the way for capability grants and further learning opportunities.

Responses

Response samples

Content type
application/json

Marks the enrollment as complete and returns the completion details.

{
  • "enrollment_id": "123e4567-e89b-12d3-a456-426614174000",
  • "status": "completed",
  • "completed_at": "2023-10-12T08:45:00Z"
}

ProgressTracking

Update Learner's Academic Progress

Track learners' journey through your educational content with precision. This endpoint empowers educators by recording progress metrics, enabling tailored learning paths and ensuring every student reaches their full potential.

Request Body schema: application/json
required
enrollment_id
required
string

Unique identifier for the learner's enrollment.

overall_progress
required
integer

Progress percentage, must be an integer between 0 and 100.

lesson_id
string

Identifier of the last lesson accessed by the learner.

completed
boolean

Indicates if the last lesson was completed.

time_spent_seconds
integer

Time spent on the last lesson in seconds.

interactions
object

Additional data regarding learner interactions during the lesson.

Responses

Request samples

Content type
application/json

This example illustrates a progress update for a learner who completed the lesson with some interaction data.

{
  • "enrollment_id": "enroll_12345",
  • "overall_progress": 75,
  • "lesson_id": "lesson_6789",
  • "completed": true,
  • "time_spent_seconds": 3600,
  • "interactions": {
    }
}

Response samples

Content type
application/json
{
  • "progress_id": "prog_rec_98765",
  • "enrollment_id": "enroll_12345",
  • "lesson_id": "lesson_6789",
  • "completed": true,
  • "recorded_at": "2023-10-08T14:53:00Z",
  • "overall_progress": 75,
  • "next_lesson": null
}

Progress Tracking

Retrieve enrollment progress details

Unlock the journey of learning by delving into the progress of a specific enrollment. This endpoint provides a window into a learner's path within a course, offering insights into their current status, progress milestones, and activity history. It's a tool for educators to tailor support and for learners to reflect on their educational voyage.

Responses

Response samples

Content type
application/json

A learner enrolled in the 'Advanced Data Science' course showing significant progress.

{
  • "enrollment_id": "enroll123",
  • "course_id": "course456",
  • "course_title": "Advanced Data Science",
  • "overall_progress": 75,
  • "modules": [ ],
  • "next_lesson": "lesson789",
  • "total_time_spent_minutes": 1200,
  • "last_activity": "2023-10-05T14:48:00Z",
  • "on_track": true,
  • "status": "enrolled",
  • "enrolled_at": "2023-01-10T10:00:00Z",
  • "completed_at": null,
  • "progress_context": { }
}

Workforce

Retrieve worker availability status

Discover the availability of a worker within the HUMAN network by querying their Passport DID. This endpoint empowers task coordinators to efficiently allocate human resources, ensuring balanced workloads and optimal performance across organizations.

Responses

Response samples

Content type
application/json

An example response showing a worker with available capacity.

{
  • "did": "did:human:abc123",
  • "status": "available",
  • "current_load": {
    },
  • "by_org": [
    ],
  • "schedule": null,
  • "performance_metrics": null
}

Create a new workflow definition

Launch the orchestration of human and AI tasks by defining a new workflow. This endpoint allows you to specify a series of steps, each identified by a unique step_id, aimed at automating complex processes with precision and safety through the HUMAN protocol.

Request Body schema: application/json
required
workflow_name
required
string

The human-readable name of the workflow.

required
Array of objects

An ordered list of steps that make up the workflow.

escalation_rules
object

Optional rules for handling task escalations.

Responses

Request samples

Content type
application/json

Define a simple workflow with two steps to process invoices.

{
  • "workflow_name": "Invoice Processing",
  • "steps": [
    ],
  • "escalation_rules": {
    }
}

Response samples

Content type
application/json
{
  • "workflow_id": "wf_1234567890",
  • "status": "created",
  • "created_at": "2023-10-12T14:48:00.000Z",
  • "estimated_throughput": "~100 items/hour (MVP estimate)"
}

Execute a workflow in the workforce system

Embark on a seamless journey of workflow execution within the HUMAN platform. This endpoint breathes life into your workflows, orchestrating tasks with precision and tracking their progress meticulously. It serves as the beating heart of operations, ensuring that tasks are not only executed but also monitored for efficiency and success.

Request Body schema: application/json
required
input_data
required
Array of objects

Array of data items to process within the workflow

priority
string
Enum: "high" "normal" "low"

Priority level of the execution

Responses

Request samples

Content type
application/json

Executing a workflow with standard priority

{
  • "input_data": [
    ],
  • "priority": "normal"
}

Response samples

Content type
application/json
null

Retrieve Task Payment Details

Uncover the financial journey of a task through its payment details. This endpoint is your key to understanding the monetary status of a task, revealing insights about payments made and pending, tied to the workers' identities. Dive into the ledger of a task's lifecycle and manage your workforce with precision.

Responses

Response samples

Content type
application/json

Fetches payment details for a task completed by a worker with all payment attributes filled.

{
  • "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "payment_status": "completed",
  • "worker_did": "did:example:123456789abcdefghi",
  • "amount": 150.75,
  • "currency": "USD",
  • "paid_at": "2023-11-01T15:30:45Z",
  • "payment_method": "credit_card",
  • "transaction_id": "txn_1A2B3C4D5E"
}

Retrieve earnings for a specific agent

Dive into the earnings of an agent over a specified period, allowing organizations to track performance and pending payments seamlessly. This endpoint exists to provide transparency and accountability in payment processing, ensuring agents are rewarded accurately for their contributions.

Responses

Response samples

Content type
application/json

Earnings details for an agent from Acme Corporation over the last 30 days.

{
  • "did": "did:example:123456789abcdefghi",
  • "period": "30 days",
  • "total_earnings": 1500.75,
  • "currency": "USD",
  • "tasks_completed": 50,
  • "avg_earnings_per_task": 30.01,
  • "payment_breakdown": [
    ],
  • "pending_payments": 300.5
}

Initiate a payout for workforce members

Embark on the journey of rewarding your workforce. This endpoint allows organizations to seamlessly initiate payouts to their workforce with the assurance of cryptographic identity verification and provenance tracking. It's designed to ensure that the right amount reaches the right individual securely and efficiently.

Request Body schema: application/json
required
did
required
string

The Decentralized Identifier (DID) of the recipient's Passport.

amount
required
number >= 0.01

The amount to be paid out.

currency
string

The currency in which the payout will be made. Defaults to USD.

destination
required
object

Destination details for the payout.

Responses

Request samples

Content type
application/json

A typical payout request for an employee with a specific DID.

{
  • "did": "did:example:123456789abcdefghi",
  • "amount": 1500,
  • "currency": "USD",
  • "destination": {
    }
}

Response samples

Content type
application/json
null

Retrieve workforce analytics metrics

In the realm of Human-AI collaboration, understanding workforce dynamics is crucial. This endpoint provides a window into the metrics that matter—how tasks are flowing, who's active, and financial summaries—over selectable periods. It's a vital tool for organizations like 'acme' to optimize their human and AI resources.

Responses

Response samples

Content type
application/json

An example showing metrics for the 'acme' organization over a 7-day period.

{
  • "period": "7 days",
  • "total_tasks": 120,
  • "completed_tasks": 100,
  • "completion_rate": 0.833,
  • "avg_completion_time": 360,
  • "avg_quality_score": null,
  • "active_workers": 25,
  • "total_payments": 1500.5,
  • "currency": "USD",
  • "task_breakdown": {
    }
}

Discover Open Opportunities Effortlessly

Unlock a world of possibilities with our marketplace-style discovery endpoint. This tool connects organizations with open opportunities tailored to specific locations and capabilities, ensuring the right skills meet the right needs in real-time.

Responses

Response samples

Content type
application/json
{
  • "location": "USA",
  • "capability": "capability://data-entry",
  • "opportunities": [
    ]
}

Create a new workforce task for an organization

This endpoint empowers internal and HumanOS callers to create tasks that are seamlessly integrated into the workforce task queue. By providing a programmatic interface, it allows for the automation and orchestration of task assignments, ensuring that tasks are efficiently routed and managed according to the organization's needs.

Request Body schema: application/json
required
task_type
required
string

The type of task to be created, defining its nature and handling.

priority
string
Enum: "high" "normal" "low"

The priority level of the task, influencing its position in the queue.

sla_minutes
integer >= 0

Service Level Agreement time in minutes, indicating the expected completion time.

source
string
Default: "api"

The origin of the task creation request.

payload
object

Additional data relevant to the task, specific to the task type.

required_caps
Array of strings

Responses

Request samples

Content type
application/json

Creating a normal priority task for invoice processing

{
  • "task_type": "invoice_processing",
  • "priority": "normal",
  • "sla_minutes": 30,
  • "source": "api",
  • "payload": {
    },
  • "required_caps": [
    ]
}

Response samples

Content type
application/json
{
  • "task_id": "task-67890",
  • "queue_id": "queue-123",
  • "assignment_id": null,
  • "worker_id": null,
  • "status": "queued"
}

Retrieve task status in workforce management

Discover the current status of a task within the workforce management system. This endpoint helps organizations monitor ongoing tasks, ensuring timely completion and efficient resource allocation by providing detailed insights into each task's lifecycle.

Responses

Response samples

Content type
application/json
{
  • "task_id": "task-12345",
  • "status": "in-progress",
  • "assigned_worker": "worker-6789",
  • "completed_at": null
}

Retrieve task outcome history

Uncover the complete history of a task's outcomes, providing a transparent view into its provenance timeline. This endpoint offers organizations a way to trace the evolution of a task, ensuring clarity and accountability in workforce management.

Responses

Response samples

Content type
application/json

Retrieve all outcomes for task ID 123 from organization 'acme'.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Submit results for a workforce task

In the bustling world of HUMAN orchestration, submitting your task results is the final triumphant step. This endpoint ensures that your contributions to the workforce are recorded, verified, and directed towards the next stage of processing. It embodies the harmonious collaboration between human workers and AI, ensuring each task is completed with transparency and efficiency.

Request Body schema: application/json
required
result
required
object

The result data of the task, encapsulating the output produced by the worker.

time_spent
integer

Time spent by the worker on this task, in minutes.

difficulty_rating
integer

A subjective rating of task difficulty provided by the worker, on a scale from 1 to 5.

Responses

Request samples

Content type
application/json

Submission of results for processing an invoice in the 'acme' organization.

{
  • "result": {
    },
  • "time_spent": 45,
  • "difficulty_rating": 3
}

Response samples

Content type
application/json
{
  • "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  • "status": "submitted",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "next_step": "quality_review"
}

Submit task review results

In the world of AI-human collaboration, every task completed deserves a review. This endpoint empowers you to submit your verdict on a task's outcome, ensuring quality and fostering continuous improvement in shared workflows.

Request Body schema: application/json
required
approved
required
boolean

Indicates if the task result is approved.

quality_score
number [ 0 .. 100 ]

A score reflecting the quality of the completed task.

feedback
string

Optional feedback on the task result.

corrections
string

Details of any corrections needed.

Responses

Request samples

Content type
application/json

Submitting a positive review with high quality score.

{
  • "approved": true,
  • "quality_score": 95,
  • "feedback": "Exceptional work, no corrections needed."
}

Response samples

Content type
application/json
null

Retrieve task details for a workforce

Explore the inner workings of your organization by retrieving detailed information about a specific workforce task. This endpoint not only reveals the task's status but also uncovers its journey through the organizational queue and current assignment state, providing a comprehensive view of task orchestration.

Responses

Response samples

Content type
application/json

A scenario where a task has been completed by a worker.

{
  • "task_id": "task-123",
  • "org_id": "org-acme",
  • "queue_name": "Invoice Processing",
  • "assignment_id": "assign-456",
  • "worker_id": "worker-789",
  • "assignment_state": "completed",
  • "assigned_at": "2023-10-10T14:48:00Z",
  • "started_at": "2023-10-10T14:50:00Z",
  • "completed_at": "2023-10-10T15:00:00Z"
}

Retrieve workforce queue details for organization

Unleash the power of your organization by accessing a detailed view of workforce queues. This endpoint allows you to harness insights into task distribution, easily identifying pending and active tasks across different queues. Perfect for managers seeking to optimize task allocation and ensure smooth operations.

Responses

Response samples

Content type
application/json

A snapshot of task queues for Acme Corp, illustrating pending and active tasks.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": false
}

Create a new workforce queue

In a dynamic organization, managing tasks efficiently is key. This endpoint allows you to create a new queue within your organization's workforce, ensuring that tasks are routed effectively to the right personnel. By defining task types and worker capabilities, you tailor the flow to meet your operational demands.

Request Body schema: application/json
required
name
required
string

The name of the queue

description
string

A brief description of the queue

task_types
Array of strings

List of task types assigned to this queue

worker_ids
Array of strings

Identifiers of workers eligible for this queue

capability_filter
object

Criteria to filter workers based on capabilities

visibility
string
Enum: "internal_only" "public"

Visibility status of the queue

Responses

Request samples

Content type
application/json

Demonstrates creating a queue for handling customer support tasks

{
  • "name": "Customer Support",
  • "description": "Handles all incoming customer queries",
  • "task_types": [
    ],
  • "worker_ids": [
    ],
  • "capability_filter": {
    },
  • "visibility": "internal_only"
}

Response samples

Content type
application/json
{
  • "queue_id": "queue789",
  • "org_id": "acme",
  • "name": "Customer Support",
  • "description": "Handles all incoming customer queries",
  • "task_types": [
    ],
  • "worker_ids": [
    ],
  • "capability_filter": {
    },
  • "visibility": "internal_only"
}

Update workforce queue details

Refine your organization's task orchestration by updating key attributes of a workforce queue. Whether enhancing the queue's purpose with a fresh name or adjusting its visibility, this endpoint empowers you to keep task routing aligned with evolving business needs.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Claim next task from workforce queue

This endpoint empowers a registered worker to claim the oldest eligible task from their organization's designated queue. Utilizing a safe, concurrent mechanism, it ensures tasks are claimed exactly once, preventing overlaps and ensuring integrity in task assignment.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json

A worker with a valid Passport DID claims a task.

{
  • "delegation": {
    }
}

Response samples

Content type
application/json
{
  • "taskId": "task789",
  • "taskDetails": {
    }
}

Retrieve organization's task routing rules

In the bustling world of HUMAN's orchestration, routing rules are the silent conductors ensuring tasks land in the right queues. This API endpoint unveils the orchestration within your organization, mapping each task type to its designated queue, ensuring efficiency and safety in human-AI collaboration.

Responses

Response samples

Content type
application/json

A snapshot of routing rules for an organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": false
}

Update Workforce Routing Rule Details

Fine-tune the orchestration of tasks within your organization by updating a specific workforce routing rule. This endpoint allows you to modify key attributes of a routing rule, ensuring that tasks are efficiently managed and aligned with your organization's evolving needs.

Request Body schema: application/json
required
default_queue_id
string

The ID of the default queue to assign tasks to. Must belong to the organization.

requires_human
boolean

Flag indicating if human intervention is required for tasks routed by this rule.

reviewer_count
integer

The number of reviewers required for tasks.

escalation_policy
object

JSON object detailing the escalation policy.

Responses

Request samples

Content type
application/json

Example showcasing updating default queue and reviewer count for a rule.

{
  • "default_queue_id": "queue-1234",
  • "reviewer_count": 2
}

Response samples

Content type
application/json
{
  • "rule_id": "rule-5678",
  • "org_id": "acme",
  • "default_queue_id": "queue-1234",
  • "requires_human": true,
  • "reviewer_count": 2,
  • "escalation_policy": { }
}

Retrieve workforce workers by organization

Dive into the dynamic world of workforce management by fetching a curated list of workers associated with your organization. This endpoint empowers you to filter workers by status and paginate results, ensuring you always have the right people at your fingertips for an efficient operation.

Responses

Response samples

Content type
application/json

Fetching workers for the 'acme' organization with 2 active assignments.

{
  • "data": [
    ],
  • "hasMore": false,
  • "limit": 10,
  • "cursorField": "created_at"
}

Initiate a workforce assignment

Empower your workforce by starting an assignment with precision. This endpoint ensures that tasks are commenced by authorized individuals, maintaining the integrity and flow of organizational operations.

Responses

Response samples

Content type
application/json
null

Complete workforce assignment with decision

Empower your workforce with decisive closure! This endpoint allows a human worker to submit a final decision on a task, completing the assignment with clarity and precision. By enforcing explicit decision-making, it ensures transparency and accountability in task management.

Request Body schema: application/json
required
decision
required
string
Enum: "approved" "rejected" "needs_changes" "escalated"

The final decision made on the assignment.

notes
string

Additional notes required if decision is 'rejected' or 'needs_changes'.

risk_class
string

Optional risk classification for the decision.

artifacts
object

Optional artifacts related to the decision.

Responses

Request samples

Content type
application/json

Submitting an 'approved' decision for a completed task.

{
  • "decision": "approved",
  • "notes": "All criteria met. Proceed with closure.",
  • "risk_class": "low",
  • "artifacts": { }
}

Response samples

Content type
application/json
null

Match workforce based on capabilities

In a world where tasks demand the right talents, this endpoint finds workers with the exact capabilities your organization needs. By specifying required skills, you enable the HUMAN platform to orchestrate a match that optimizes task routing, ensuring tasks are handled by the most qualified individuals.

Request Body schema: application/json
required
required
Array of objects

List of capabilities with optional minimum weights

limit
integer <= 100

Maximum number of matches to return

Responses

Request samples

Content type
application/json

Find workers with specific capabilities

{
  • "required_capabilities": [
    ],
  • "limit": 10
}

Response samples

Content type
application/json
{
  • "matches": [
    ],
  • "total_matches": 1
}

Stream workforce events for an organization

Connect to a real-time stream of workforce events tailored for your organizational role. Designed to keep human agents and AI systems synchronized, this endpoint ensures you never miss an important update in your operational sphere.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Update workforce routing configuration

Fine-tune your organization's task routing by configuring workforce settings. This endpoint ensures that tasks are directed efficiently to human and AI agents using up-to-date configurations, providing a seamless orchestration experience.

Request Body schema: application/json
required
required
object

Dynamic routing configuration settings

Responses

Request samples

Content type
application/json

Configure routing for Acme's invoice processing tasks to ensure tasks are managed efficiently across teams.

{
  • "config": {
    }
}

Response samples

Content type
application/json
null

Retrieve work items for an organization

Dive into the heart of your organization's operations by exploring a curated list of work items. This endpoint empowers you to filter tasks based on status, urgency, and routing, ensuring you're always on top of what matters most. It's designed to help you manage tasks with precision, ensuring that nothing slips through the cracks.

Responses

Response samples

Content type
application/json

A response showing a paginated list of work items, with filtering applied.

{
  • "data": [
    ],
  • "next_cursor": "eyJjcmVhdGVkX2F0IjogIjIwMjMtMTAtMDJUMTQ6MzA6MDBaIiwgIndvcmtfaXRlbV9pZCI6ICJ3aTEyMzQ1In0="
}

Create a new workforce work item

This endpoint orchestrates the creation of a new work item within the HUMAN platform's workforce module. It enables organizations to delegate tasks efficiently while ensuring compliance through cryptographic identity verification and capability tracking. Whether you're routing tasks to a personal agent or a team, this endpoint ensures the task is correctly assigned and tracked.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve detailed work item information

Unlock the intricate details of a specific work item within the HUMAN ecosystem. This endpoint enables organizations to track and manage workforce tasks with precision, ensuring each task aligns with their strategic goals and operational needs.

Responses

Response samples

Content type
application/json

Details of a work item processed by Acme Corp

{
  • "id": "wi-123456",
  • "org_did": "did:human:acme",
  • "installation_id": "inst-001",
  • "renderer_id": "renderer-007",
  • "artifact_id": "artifact-789",
  • "status": "in_progress",
  • "routed_to_type": "agent",
  • "routed_to_id": "agent-42",
  • "routed_by": "agent-5",
  • "urgency": "high",
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-02T15:30:00Z",
  • "completed_at": null,
  • "actions_taken": "Reviewed documentation, initiated process",
  • "feedback_emitted": "Positive feedback"
}

Execute actions on workforce work items

This endpoint is a cornerstone of dynamic collaboration, enabling authorized agents to execute specific actions on work items in the HUMAN platform. By orchestrating tasks, it ensures that work items are processed efficiently and securely, aligning with organizational needs.

Request Body schema: application/json
required
action_id
required
string

The identifier for the action to be executed.

note
string

An optional note detailing the action.

revised_content
string

Revised content for edit actions.

form_data
object

Additional data for form-driven actions.

org_did
required
string

The decentralized identifier of the organization.

Responses

Request samples

Content type
application/json

An agent from 'acme' organization marking a task as 'approved' with additional notes.

{
  • "action_id": "approve",
  • "note": "Reviewed and approved by manager",
  • "org_did": "did:org:acme123"
}

Response samples

Content type
application/json
{
  • "id": "workitem123",
  • "status": "in_progress",
  • "actions_taken": [
    ]
}

Stream Workforce Work Item Updates

Dive into the heart of your operations by streaming real-time updates for a specific work item. This endpoint ensures you're always in sync, providing live status changes and actions performed on your work items, crucial for time-sensitive tasks and responsive workflows.

Responses

Response samples

Content type
application/json
{
  • "event": "connected",
  • "data": {
    }
}

Availability

Retrieve worker availability status

Discover the availability of a worker within the HUMAN network by querying their Passport DID. This endpoint empowers task coordinators to efficiently allocate human resources, ensuring balanced workloads and optimal performance across organizations.

Responses

Response samples

Content type
application/json

An example response showing a worker with available capacity.

{
  • "did": "did:human:abc123",
  • "status": "available",
  • "current_load": {
    },
  • "by_org": [
    ],
  • "schedule": null,
  • "performance_metrics": null
}

Orchestration

Create a new workflow definition

Launch the orchestration of human and AI tasks by defining a new workflow. This endpoint allows you to specify a series of steps, each identified by a unique step_id, aimed at automating complex processes with precision and safety through the HUMAN protocol.

Request Body schema: application/json
required
workflow_name
required
string

The human-readable name of the workflow.

required
Array of objects

An ordered list of steps that make up the workflow.

escalation_rules
object

Optional rules for handling task escalations.

Responses

Request samples

Content type
application/json

Define a simple workflow with two steps to process invoices.

{
  • "workflow_name": "Invoice Processing",
  • "steps": [
    ],
  • "escalation_rules": {
    }
}

Response samples

Content type
application/json
{
  • "workflow_id": "wf_1234567890",
  • "status": "created",
  • "created_at": "2023-10-12T14:48:00.000Z",
  • "estimated_throughput": "~100 items/hour (MVP estimate)"
}

Resolve and execute companion commands

In the intricate dance of Human-AI orchestration, this endpoint serves as the maestro, interpreting and executing commands within the HUMAN ecosystem. It ensures that commands are correctly resolved and executed, enhancing the synergy between human intent and AI capabilities.

Request Body schema: application/json
required
input
required
string

The command input string to be resolved

Responses

Request samples

Content type
application/json

Demonstrates resolving a command using a slash-prefixed format

{
  • "input": "/acme.invoice.process"
}

Response samples

Content type
application/json
null

Proxy API requests for Human-AI orchestration

This endpoint acts as a versatile proxy for various Human-AI orchestration tasks. By delegating operations, it empowers users to seamlessly interact with different components of the HUMAN platform, ensuring security and efficiency.

Request Body schema: application/json
required
tool
required
string

The tool to execute, e.g., 'human.passport.get'.

object

Arguments required by the specified tool.

Responses

Request samples

Content type
application/json

An example showing how to retrieve a passport by ID.

{
  • "tool": "human.passport.get",
  • "arguments": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

Finance

Retrieve Task Payment Details

Uncover the financial journey of a task through its payment details. This endpoint is your key to understanding the monetary status of a task, revealing insights about payments made and pending, tied to the workers' identities. Dive into the ledger of a task's lifecycle and manage your workforce with precision.

Responses

Response samples

Content type
application/json

Fetches payment details for a task completed by a worker with all payment attributes filled.

{
  • "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "payment_status": "completed",
  • "worker_did": "did:example:123456789abcdefghi",
  • "amount": 150.75,
  • "currency": "USD",
  • "paid_at": "2023-11-01T15:30:45Z",
  • "payment_method": "credit_card",
  • "transaction_id": "txn_1A2B3C4D5E"
}

Payments

Retrieve earnings for a specific agent

Dive into the earnings of an agent over a specified period, allowing organizations to track performance and pending payments seamlessly. This endpoint exists to provide transparency and accountability in payment processing, ensuring agents are rewarded accurately for their contributions.

Responses

Response samples

Content type
application/json

Earnings details for an agent from Acme Corporation over the last 30 days.

{
  • "did": "did:example:123456789abcdefghi",
  • "period": "30 days",
  • "total_earnings": 1500.75,
  • "currency": "USD",
  • "tasks_completed": 50,
  • "avg_earnings_per_task": 30.01,
  • "payment_breakdown": [
    ],
  • "pending_payments": 300.5
}

Initiate a payout for workforce members

Embark on the journey of rewarding your workforce. This endpoint allows organizations to seamlessly initiate payouts to their workforce with the assurance of cryptographic identity verification and provenance tracking. It's designed to ensure that the right amount reaches the right individual securely and efficiently.

Request Body schema: application/json
required
did
required
string

The Decentralized Identifier (DID) of the recipient's Passport.

amount
required
number >= 0.01

The amount to be paid out.

currency
string

The currency in which the payout will be made. Defaults to USD.

destination
required
object

Destination details for the payout.

Responses

Request samples

Content type
application/json

A typical payout request for an employee with a specific DID.

{
  • "did": "did:example:123456789abcdefghi",
  • "amount": 1500,
  • "currency": "USD",
  • "destination": {
    }
}

Response samples

Content type
application/json
null

Retrieve Payment Boundaries for Actions

Dive into the realm of HumanOS task routing by exploring payment boundaries for specific actions. This endpoint helps organizations understand financial limits tied to their actions, ensuring AI interactions remain within budgetary constraints.

Responses

Response samples

Content type
application/json

An example where the 'acme' organization checks the payment boundary for processing invoices.

{
  • "action": "process_invoice",
  • "limit": 1000,
  • "currency": "USD"
}

Analytics

Retrieve workforce analytics metrics

In the realm of Human-AI collaboration, understanding workforce dynamics is crucial. This endpoint provides a window into the metrics that matter—how tasks are flowing, who's active, and financial summaries—over selectable periods. It's a vital tool for organizations like 'acme' to optimize their human and AI resources.

Responses

Response samples

Content type
application/json

An example showing metrics for the 'acme' organization over a 7-day period.

{
  • "period": "7 days",
  • "total_tasks": 120,
  • "completed_tasks": 100,
  • "completion_rate": 0.833,
  • "avg_completion_time": 360,
  • "avg_quality_score": null,
  • "active_workers": 25,
  • "total_payments": 1500.5,
  • "currency": "USD",
  • "task_breakdown": {
    }
}

Retrieve Task Quality Analytics

Dive into the heart of HUMAN's task quality analytics to uncover the intricate balance of human and AI decision-making. This endpoint provides a snapshot of the quality metrics for a specific task, offering insights into reviewer consensus, accuracy metrics, and worker performance. It's a window into the orchestration of human and AI interactions, ensuring tasks meet the highest standards.

Responses

Response samples

Content type
application/json
{
  • "task_id": "123e4567-e89b-12d3-a456-426614174000",
  • "quality_score": 0.96,
  • "reviewer_consensus": 0.96,
  • "accuracy_metrics": {
    },
  • "worker_performance": {
    },
  • "feedback": "Excellent work, minor adjustments needed."
}

Retrieve analytics for a marketplace asset

Dive into the heart of your asset's performance with this endpoint. Designed for publishers and administrators, it surfaces valuable metrics like installations, usage, and pseudo-revenue. Understanding these analytics helps you optimize your asset's presence in the marketplace, driving strategic decisions and growth.

Responses

Response samples

Content type
application/json

An example showing analytics for an asset over a 30-day period.

{
  • "asset_id": "asset123",
  • "asset_name": "AI Invoice Processor",
  • "asset_type": "application",
  • "trust_tier": "high",
  • "period": {
    },
  • "installs": {
    },
  • "usage": {
    },
  • "revenue": {
    },
  • "top_orgs_by_usage": [
    ]
}

Retrieve 30-day credential usage statistics

Unlock insights into your system's performance by examining detailed 30-day usage statistics for a specific credential. This endpoint provides a comprehensive overview, including invocation counts, success and failure rates, and cost metrics, empowering you to optimize resource allocation and enhance operational efficiency.

Responses

Response samples

Content type
application/json

A snapshot of how Acme Corp's credential is performing over the last month

{
  • "credential_id": "cred-1234",
  • "period": "30_days",
  • "total_invocations": 1500,
  • "successful_invocations": 1450,
  • "failed_invocations": 50,
  • "total_cost_usd": 123.45,
  • "total_tokens_used": 7500,
  • "avg_duration_ms": 235.67,
  • "last_used_at": "2023-10-01T12:34:56Z",
  • "most_used_operation": "processInvoice"
}

Retrieve Fraud Metrics for Organization

Discover insights into your organization's fraud management with a comprehensive overview of fraud metrics. Use this endpoint to access key statistics, ensuring your team stays one step ahead in the fight against fraud. The metrics are meticulously calculated based on recent activities, providing both cached results for efficiency and live data for accuracy.

Responses

Response samples

Content type
application/json
{
  • "period": "30d",
  • "computed_at": "2023-10-05T14:48:00Z",
  • "source": "live_aggregate",
  • "metrics": {
    }
}

Retrieve agent cost breakdown

Explore the detailed cost analysis of an agent over a specified period. This endpoint unveils the financial footprint of AI interactions, empowering organizations to optimize resource allocation and manage budgets effectively.

Responses

Response samples

Content type
application/json

Cost breakdown example for Acme's AI Agent over a 7-day period.

{
  • "total_cost_usd": 349.5,
  • "period": "7d",
  • "by_day": [
    ],
  • "top_executions": [
    ]
}

Retrieve detailed compute billing insights

Dive into the details of your organization's compute billing usage. This endpoint empowers administrators to analyze compute costs, track resource consumption, and optimize expenses by providing granular insights into billing events. It exists to ensure transparency and promote informed decision-making within your organization.

Responses

Response samples

Content type
application/json

An example response showing detailed billing events for an organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "nextCursor": "evt_01G5T8V2YZCGT4T9B4STZ8VXW3"
}

Retrieve compute billing summary

Uncover a detailed breakdown of compute usage costs. This endpoint empowers organizations to gain insights into their resource consumption, enabling data-driven decisions on budgeting and optimization. Dive deep into per-user, per-app, and per-model analytics to visualize spending patterns.

Responses

Response samples

Content type
application/json

A snapshot of TechGuru's compute resource usage over the past month.

{
  • "period": {
    },
  • "by_user": [
    ],
  • "by_model": [
    ],
  • "by_feature": [
    ]
}

Retrieve Workflow Analytics by ID

Delve into the analytics of your workflows with precision and clarity. This endpoint reveals insightful metrics, allowing organizations to optimize Human-AI orchestration. Discover performance trends and identify areas for improvement to enhance operational efficacy.

Responses

Response samples

Content type
application/json

Analytics for Acme Corp's invoice processing workflow showing success rates and improvement suggestions.

{
  • "run_counts": {
    },
  • "success_rate": 0.8,
  • "fallback_rate": 0.1,
  • "approval_frequency": 0.05,
  • "escalation_rate": 0.05,
  • "workforce_handoff_rate": 0.2,
  • "avg_completion_ms": 1500,
  • "connector_failure_rate": 0.02,
  • "step_failure_breakdown": {
    },
  • "improvement_suggestions": [
    ]
}

Retrieve monthly capability growth data

Explore the trajectory of a specific capability over time to understand patterns and make informed decisions. This endpoint provides a historical view of capability grants, helping organizations track their evolution and assess future trends.

Responses

Response samples

Content type
application/json

Retrieving growth data for capability 'invoice-processing' for DID 'did:example:acme123'.

{
  • "did": "did:example:acme123",
  • "capability_id": "invoice-processing",
  • "timeframe": "90d",
  • "data_points": [
    ],
  • "trend": "improving",
  • "growth_rate": "+5.88% vs prior weight",
  • "weight_source": "capability_node_weights",
  • "projection": {
    }
}

Quality

Retrieve Task Quality Analytics

Dive into the heart of HUMAN's task quality analytics to uncover the intricate balance of human and AI decision-making. This endpoint provides a snapshot of the quality metrics for a specific task, offering insights into reviewer consensus, accuracy metrics, and worker performance. It's a window into the orchestration of human and AI interactions, ensuring tasks meet the highest standards.

Responses

Response samples

Content type
application/json
{
  • "task_id": "123e4567-e89b-12d3-a456-426614174000",
  • "quality_score": 0.96,
  • "reviewer_consensus": 0.96,
  • "accuracy_metrics": {
    },
  • "worker_performance": {
    },
  • "feedback": "Excellent work, minor adjustments needed."
}

Templates

Retrieve Agent Templates from Marketplace

Uncover the treasure trove of agent templates available in the HUMAN marketplace. This endpoint empowers you to explore a collection of predefined task orchestrations, essential for any organization looking to optimize human-AI collaboration swiftly.

Responses

Response samples

Content type
application/json

Fetching the first page of templates for organization 'acme'.

{
  • "data": [
    ],
  • "limit": 2,
  • "cursor": "opaque-cursor-string",
  • "hasMore": true
}

Retrieve marketplace template details

Explore the intricate details of a specific template from our marketplace. This endpoint serves as your gateway to understanding the capabilities and assets encapsulated within each template, bringing clarity and depth to your selection process.

Responses

Response samples

Content type
application/json

A comprehensive template used by Acme Corp for processing invoices.

{
  • "id": "t123",
  • "slug": "acme-invoice-template",
  • "name": "Acme Invoice",
  • "description": "A template for automating invoice processing at Acme Corp.",
  • "manifest_json": {
    },
  • "version": "1.2.0",
  • "asset_type": "financial"
}

Install a Marketplace Template

Install a chosen template from the marketplace into your organization's workspace. This endpoint empowers organizations to rapidly deploy pre-configured workflows or agents, streamlining operations and enhancing productivity.

Request Body schema: application/json
required
name_override
string

A new name for the template within your organization.

Responses

Request samples

Content type
application/json

Install a template with a custom name.

{
  • "name_override": "Custom Workflow for Acme Inc."
}

Response samples

Content type
application/json

A workflow template named 'Custom Workflow for Acme Inc.' was installed successfully.

{
  • "id": "workflow-12345",
  • "name": "Custom Workflow for Acme Inc.",
  • "orgId": "org-acme"
}

Reviews

Fetch reviews for a marketplace asset

Discover the insights and feedback from users for a specific asset on the Developer Home page. This endpoint exists to provide transparency and assist developers in improving their offerings by learning from user experiences.

Responses

Response samples

Content type
application/json

A list of reviews for the asset with ID 'asset123'.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursor": null,
  • "hasMore": false
}

Asset Management

Uninstall asset with delegation revocation

Uninstall a marketplace asset, cascading the removal of associated delegations. This endpoint is vital for maintaining clean operational environments by ensuring that unused assets do not retain lingering permissions, thus upholding security and efficiency.

Request Body schema: application/json
required
asset_id
required
string

The unique identifier of the asset to be uninstalled.

org_did
required
string

The decentralized identifier for the organization.

Responses

Request samples

Content type
application/json

Uninstall an asset from the 'acme' organization.

{
  • "asset_id": "asset_12345",
  • "org_did": "did:example:acme"
}

Response samples

Content type
application/json
{
  • "uninstalled": true,
  • "installation": {
    }
}

Review

Retrieve pending marketplace asset reviews

In the vibrant ecosystem of the HUMAN platform, the review queue serves as a crucial checkpoint for marketplace assets awaiting human scrutiny. This endpoint invites administrators to survey the pending and escalated items, ensuring that each asset aligns with the platform's standards and values. By scrutinizing these assets, administrators uphold the integrity and safety that HUMAN users rely upon.

Responses

Response samples

Content type
application/json

An example showing a list of assets from Acme Corp awaiting review.

{
  • "data": [
    ],
  • "hasMore": true,
  • "cursor": "eyJjcmVhdGVkX2F0IjoiMjAyMy0wOS0zMFQxMTozMzo1NVoiLCJpZCI6ImFzc2V0LTEyMyJ9"
}

Automate Marketplace Review Process

Embark on a journey to ensure your marketplace listings meet HUMAN platform standards through automated checks. This endpoint not only verifies your agent's installation manifest but also assesses eligibility for the prestigious Autonomous badge. This pre-submission tool is your ally in maintaining high-quality entries.

Request Body schema: application/json
required
agent_id
required
string

Unique identifier for the agent

required
object

Agent's installation manifest

openapi_spec
object

OpenAPI specification for the agent

request_badge
boolean

Flag to request Autonomous badge check

Responses

Request samples

Content type
application/json

Reviewing a standard agent's manifest with a request for an Autonomous badge.

{
  • "agent_id": "agent_12345",
  • "manifest": {
    },
  • "openapi_spec": {
    },
  • "request_badge": true
}

Response samples

Content type
application/json
{
  • "review": {
    },
  • "badge": {
    }
}

Asset Control

Decide on Asset Review Outcome

Empower human reviewers to influence the marketplace by approving, rejecting, or requesting changes to assets. This decision-making endpoint is pivotal in ensuring asset quality and compliance, particularly when AI alone cannot guarantee safety or fairness.

Request Body schema: application/json
required
decision
required
string
Enum: "approve" "reject" "request_changes"

The decision made by the reviewer.

bypass_compute_billing_gate
boolean

Flag to bypass the compute billing gate, requires admin scope.

bypass_iframe_trust_gate
boolean

Flag to bypass the iframe trust gate, requires admin scope.

notes
string

Additional notes from the reviewer about the decision.

risk_assessment
object

Optional JSON object for any risk assessments conducted.

Responses

Request samples

Content type
application/json

Approving an agent asset with a valid cost profile.

{
  • "decision": "approve",
  • "notes": "The asset meets all criteria and is ready for approval.",
  • "risk_assessment": {
    }
}

Response samples

Content type
application/json
null

Trust Management

Elevate an asset's trust tier

Promote the trust tier of a marketplace asset to enhance its credibility and unlock new capabilities. This operation is critical for assets aspiring to reach higher levels of trust and visibility, reflecting their reliability and adherence to safety standards.

Request Body schema: application/json
required
trust_tier
required
string
Enum: "community" "verified" "certified" "enterprise"

The trust level to promote the asset to

Responses

Request samples

Content type
application/json

Example of promoting an asset to the 'enterprise' trust tier.

{
  • "trust_tier": "enterprise"
}

Response samples

Content type
application/json

The asset was successfully promoted to the 'enterprise' tier.

{
  • "id": "asset-12345",
  • "trust_tier": "enterprise"
}

Lifecycle Management

Promote asset lifecycle stage within marketplace

Elevate the lifecycle stage of a marketplace asset, ensuring it meets the necessary criteria for progression. This endpoint is crucial for managing asset readiness and compliance in a structured, verifiable manner.

Request Body schema: application/json
required
to
required
string
Enum: "staging" "production"

The desired lifecycle stage to promote the asset to.

Responses

Request samples

Content type
application/json

Promoting an asset from staging to production.

{
  • "to": "production"
}

Response samples

Content type
application/json
{
  • "id": "asset-123",
  • "lifecycle_stage": "production",
  • "publisher_id": "org-789",
  • "updated_at": "2023-10-15T12:45:30Z"
}

Rollback asset lifecycle stage

Navigate the complex journey of digital assets within HUMAN's marketplace by rolling back their lifecycle stage. This endpoint empowers you to manage asset transitions with precision, ensuring the continuity and safety of AI-orchestrated tasks.

Request Body schema: application/json
required
to
required
string
Enum: "staging" "development" "production"

The desired stage to rollback to (e.g., 'staging').

Responses

Request samples

Content type
application/json

This example rolls back the asset lifecycle stage to 'staging'.

{
  • "to": "staging"
}

Response samples

Content type
application/json
null

Update Artifact Lifecycle State

This endpoint orchestrates the delicate dance of artifact lifecycle transitions within the HUMAN platform, ensuring compliance with organizational policies. It exists to securely manage the evolution of artifacts, reflecting their journey from inception to completion, while respecting the constraints of the Fourth Law policy.

Request Body schema: application/json
required
lifecycle_state
required
string
Enum: "draft" "submitted" "approved" "rejected" "archived"

The new lifecycle state for the artifact.

approval_request_id
string

The ID of the approval request, required for certain transitions.

Responses

Request samples

Content type
application/json

Transition an artifact to the approved state with a valid approval request ID.

{
  • "lifecycle_state": "approved",
  • "approval_request_id": "approval-12345"
}

Response samples

Content type
application/json
{
  • "artifact_id": "artifact-67890",
  • "lifecycle_state": "approved",
  • "updated_at": "2023-11-01T12:45:00Z"
}

Permanently retire a specified agent

In the dynamic world of human and AI collaboration, sometimes an agent's journey must conclude. This endpoint allows you to retire an agent, ensuring that it can no longer participate in the orchestration process. By doing so, organizations maintain a clean and up-to-date roster of active agents, preserving the integrity and reliability of the HUMAN platform.

Request Body schema: application/json
required
reason
string

Optional explanation for retiring the agent.

Responses

Request samples

Content type
application/json

Retiring an agent with a specific reason provided.

{
  • "reason": "Project completed, agent services no longer required"
}

Response samples

Content type
application/json

Example response after successfully retiring an agent.

{
  • "agent": {
    }
}

Activate a Builder Workflow

Transform your workflow from a dormant state into action by activating it. This endpoint exists to empower organizations to seamlessly transition workflows into an active state, ensuring tasks are ready to be processed. Whether you're launching a new project or reviving an existing one, activating workflows is a critical step in the orchestration process.

Request Body schema: application/json
required
note
string

A note providing context or rationale for activating the workflow

Responses

Request samples

Content type
application/json

Activating a workflow with a note to explain the reason

{
  • "note": "Activating for Q4 invoice processing cycle"
}

Response samples

Content type
application/json
null

Synchronization

Synchronize Marketplace Assets

In the vast ecosystem of human and AI collaboration, staying updated is crucial. This endpoint allows self-hosted platforms to synchronize with the latest approved and globally visible assets from haio.run. By leveraging this, organizations can ensure they have the most current tools and resources at their disposal, enhancing their capability graph and ensuring seamless operations.

Responses

Response samples

Content type
application/json

The response includes a list of assets that have been updated since the last sync.

{
  • "assets": [
    ],
  • "synced_at": "2023-10-07T14:35:00Z"
}

Synchronize Knowledge Base Index

Refresh your knowledge base index with a single request. This endpoint ensures that your knowledge base is current and ready to provide the most accurate information when called upon. Ideal for organizations seeking to maintain an up-to-date repository of knowledge.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json

A request to synchronize the knowledge base index from an authorized user.

{
  • "delegation": {
    }
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "synced_at": "2023-10-05T14:48:00.000Z",
  • "message": "KB index refreshed on next request (filesystem-backed)"
}

Discovery

Discover the HUMAN API's live status

This root discovery endpoint is your gateway to the HUMAN API, offering real-time insights into its operational status. It serves as the heartbeat of the HUMAN platform, ensuring that the trust layer between human decisions and machine execution remains robust and transparent.

Responses

Response samples

Content type
application/json

An example where the HUMAN API is fully operational.

{}

Discover HUMAN platform capabilities

Uncover the powerful orchestration capabilities of the HUMAN Protocol. This endpoint offers a glimpse into the platform's operational status and available paths, guiding users through a seamless integration into the future of Human-AI collaboration.

Responses

Response samples

Content type
application/json

An example of the HUMAN Protocol platform in full operational status.

{
  • "platform": "HUMΛN Orchestration Protocol",
  • "version": "v1",
  • "status": "operational",
  • "authentication": {
    },
  • "api_reference": "/v1/openapi.json",
  • "capabilities_catalog": "/v1/system-capabilities",
  • "knowledge": "https://console.haio.run/ai/llms.txt",
  • "endpoints": {
    },
  • "links": {}
}

Documentation

Fetch the HUMAN OpenAPI Specification

Unlock the full potential of HUMAN's protocol by accessing its OpenAPI specification. This endpoint serves as the key to understanding and integrating with HUMAN's complex orchestration of human and AI capabilities.

Responses

Response samples

Content type
application/json
{
  • "openapi": "3.0.1",
  • "info": {
    },
  • "paths": {
    }
}

Integration

Fetch the HUMAN OpenAPI Specification

Unlock the full potential of HUMAN's protocol by accessing its OpenAPI specification. This endpoint serves as the key to understanding and integrating with HUMAN's complex orchestration of human and AI capabilities.

Responses

Response samples

Content type
application/json
{
  • "openapi": "3.0.1",
  • "info": {
    },
  • "paths": {
    }
}

Link External Issue to Incident

In the high-stakes world of incident management, every moment counts. This endpoint empowers you to link an external issue from popular trackers like Jira or GitHub directly to an incident, ensuring seamless integration and comprehensive incident resolution history.

Request Body schema: application/json
required
provider
required
string
Enum: "linear" "jira" "github"

The external provider where the issue is tracked

external_key
required
string

A stable identifier for the issue within the external tracker

issue_url
required
string <uri>

The direct URL to the issue in the external tracker

Responses

Request samples

Content type
application/json

Linking a Jira issue to an incident

{}

Response samples

Content type
application/json
null

Retrieve organization connector credentials

Dive into the heart of connectivity! This endpoint fetches a curated list of connector credentials tied to your organization. Designed for seamless integration, it ensures that your connectors are up-to-date and ready to handle your organization's demands, showcasing their status and health.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieve all available schemas list

Dive into the intricacies of schema orchestration with this endpoint, which unveils a comprehensive list of schemas available within the HUMAN platform. Explore the structural backbone that powers the seamless Human-AI collaboration, providing you the keys to unlock deeper integrations.

Responses

Response samples

Content type
application/json

An example response showing the list of schema names available on the platform.

{
  • "items": [
    ],
  • "total": 3
}

System Health

Retrieve worker health and status overview

This endpoint provides a snapshot of the current health and status of workers within your HUMAN orchestration system. By accessing real-time connections to the Redis backend and queue statistics, you ensure seamless task execution and AI safety. This proactive insight helps maintain operational efficiency.

Responses

Response samples

Content type
application/json
{
  • "redis": {
    },
  • "queues": {
    },
  • "workers": {
    },
  • "timestamp": "2023-10-15T14:48:00.000Z"
}

Workers

Retrieve worker health and status overview

This endpoint provides a snapshot of the current health and status of workers within your HUMAN orchestration system. By accessing real-time connections to the Redis backend and queue statistics, you ensure seamless task execution and AI safety. This proactive insight helps maintain operational efficiency.

Responses

Response samples

Content type
application/json
{
  • "redis": {
    },
  • "queues": {
    },
  • "workers": {
    },
  • "timestamp": "2023-10-15T14:48:00.000Z"
}

Members

Retrieve paginated list of organization members

Discover who is part of your organization with this endpoint. It serves as a gateway to explore the human network within an organization, empowering you to manage and collaborate with your members effectively. This endpoint ensures that only authorized users can access information, maintaining privacy and data integrity.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "joined_at"
}

Membership

Add member to organization

Empower your organization's growth by adding new members who bring diverse skills and expertise. This endpoint allows you to expand your team by securely adding individuals to your organization, ensuring that only authorized personnel can perform this task.

Request Body schema: application/json
required
human_did
required
string

The Passport DID of the human being added

role
required
string

The role assigned to the new member within the organization

Responses

Request samples

Content type
application/json

This example demonstrates adding a new member as a Senior Engineer to the organization.

{
  • "human_did": "did:human:123456",
  • "role": "senior_engineer"
}

Response samples

Content type
application/json
{
  • "org_did": "did:org:acme",
  • "human_did": "did:human:123456",
  • "work_agent_did": "did:agent:123456-work-acme",
  • "role": "senior_engineer",
  • "joined_at": "2023-10-05T14:48:00.000Z",
  • "terminated_at": null,
  • "terminated_by": null,
  • "termination_reason": null
}

Terminate a member's employment

In the intricate ballet of organizational management, there comes a time when a member must exit the stage. This endpoint gracefully orchestrates the termination of a member's employment within the HUMAN platform, ensuring proper documentation and provenance. It exists to maintain order and clarity in the dynamic interplay between human and AI roles.

Request Body schema: application/json
required
reason
string

A brief explanation for the termination

Responses

Request samples

Content type
application/json

Provides a reason for the member's termination

{
  • "reason": "Position redundancy due to restructuring"
}

Response samples

Content type
application/json
{
  • "org_did": "did:org:acme",
  • "human_did": "did:human:john_doe",
  • "work_agent_did": "did:agent:agent123",
  • "role": "Software Engineer",
  • "joined_at": "2022-01-15T08:00:00Z",
  • "terminated_at": "2023-10-10T09:00:00Z",
  • "terminated_by": "did:agent:manager456",
  • "termination_reason": "Position redundancy due to restructuring"
}

Profile

Retrieve an organization's profile information

Explore the digital tapestry of an organization’s identity with this endpoint. It unveils the public profile of an organization, including its unique cryptographic identity (DID), branding elements, and provenance data. This ensures transparency and trust in interactions, vital for seamless Human-AI collaboration.

Responses

Response samples

Content type
application/json

Retrieving the profile for the fictional Acme Corporation.

{
  • "org_did": "did:example:acme123",
  • "display_name": "Acme Corporation",
  • "description": "Leading provider of innovative solutions.",
  • "website_url": "https://www.acme.com",
  • "logo_url": "https://www.acme.com/logo.png",
  • "brand_tokens": "acme2023",
  • "updated_by": "did:example:agent456",
  • "created_at": "2023-01-15T08:00:00Z",
  • "updated_at": "2023-10-05T12:00:00Z"
}

Profile Management

Update Organization Profile Details

This endpoint empowers organizations to maintain accurate and up-to-date profiles by allowing authenticated updates to their profile details. It ensures that only the rightful owner of the organization can modify its profile, safeguarding against unauthorized changes.

Request Body schema: application/json
required
Any of
display_name
required
string <= 255 characters
description
string or null
website_url
string or null
logo_url
string or null
brand_tokens
object or null

Responses

Request samples

Content type
application/json

This example demonstrates updating the display name of an organization.

{
  • "display_name": "Acme Corporation"
}

Response samples

Content type
application/json
{
  • "org_did": "did:example:123456789abcdefghi",
  • "display_name": "Acme Corporation",
  • "description": "Innovator in industry solutions",
  • "website_url": "https://acme.example.com",
  • "logo_url": "https://acme.example.com/logo.png",
  • "brand_tokens": {
    },
  • "updated_by": "did:example:agent12345",
  • "created_at": "2023-01-01T12:00:00Z",
  • "updated_at": "2023-10-01T12:00:00Z"
}

Communication

Retrieve organization communication settings

Dive into the communication preferences of an organization with this endpoint. Fetching these settings allows you to understand how the organization presents itself in communications, ensuring consistent messaging and proper routing of replies. This is crucial for maintaining a polished and professional external appearance.

Responses

Response samples

Content type
application/json

Communication settings for Acme Corporation, illustrating a typical setup.

{
  • "org_did": "did:human:acme123",
  • "send_mode": "batch",
  • "from_display_name": "Acme Support",
  • "from_email": "support@acme.com",
  • "reply_to_email": "noreply@acme.com",
  • "legal_footer": "© 2023 Acme Corporation. All rights reserved.",
  • "updated_at": "2023-09-15T14:00:00Z"
}

Initiate backchannel in duplex session

Open a direct communication channel with the AI agent during an active duplex session. This endpoint allows human operators to signal their current interaction mode, enhancing the coordination and effectiveness of the AI's response.

Request Body schema: application/json
required
style
required
string
Enum: "ack" "thinking"

The style of interaction: 'ack' for acknowledgment or 'thinking' for processing state.

Responses

Request samples

Content type
application/json

Signals the AI to acknowledge receipt of information.

{
  • "style": "ack"
}

Response samples

Content type
application/json
{
  • "session_id": "123456",
  • "sent": true
}

Initiate a companion chat session

Engage with the HUMAN platform's companion AI to facilitate seamless conversations. This endpoint is an essential part of creating interactive experiences where AI assists human users by understanding context and responding in real-time. It ensures the AI is informed by past interactions and current context, making it a valuable tool for dynamic user engagement.

Request Body schema: application/json
required
message
required
string

The message to send to the companion AI.

session_id
string

An optional identifier for the chat session to maintain context.

history
Array of strings

Optional array of previous messages for context continuity.

context
object

Additional contextual information to enhance AI understanding.

Responses

Request samples

Content type
application/json

Use this example to initiate a chat while passing previous conversation history and session ID.

{
  • "message": "How do I process invoices?",
  • "session_id": "session-abc123",
  • "history": [
    ],
  • "context": {
    }
}

Response samples

Content type
application/json

An example response where the AI provides guidance on invoice processing.

{
  • "task_id": "task-xyz456",
  • "trace_id": "trace-789xyz",
  • "result": {
    }
}

Retrieve User's C2C Inbox Messages

Dive into your collaborative journey with the C2C Inbox, where every message is a thread in the fabric of your professional narrative. This endpoint empowers users to access their cross-channel communications, reflecting the dynamic interactions in the HUMAN ecosystem.

Responses

Response samples

Content type
application/json

A user retrieves their inbox messages with a pagination cursor.

{
  • "data": [
    ],
  • "hasMore": false
}

Gates

Retrieve the Natural Gate Map

In your journey through the HUMAN ecosystem, understanding the access gates is crucial. This endpoint unveils the natural gate map, illustrating which capabilities demand specific verification levels. It's designed to empower frontends with the intelligence to guide users smoothly through their tasks, ensuring they are prepared before encountering a gate.

Responses

Response samples

Content type
application/json

A snapshot of various gates including actions and their requirements.

{
  • "gates": [
    ]
}

AI Submission

Submit a new marketplace listing

The marketplace submission endpoint is your gateway to showcasing your AI's capabilities to the world. Here, you validate your submission, undergo a rigorous automated review, and, if successful, enter the submission queue. This ensures only the best and most compliant agents make it to the HUMAN platform.

Request Body schema: application/json
required
agent_id
required
string

A unique identifier for the submitting agent.

publisher_did
required
string

The decentralized identifier (DID) of the publisher.

manifest
required
object

The detailed manifest of the agent, conforming to the InstallManifest schema.

openapi_spec
object

An optional OpenAPI specification for the agent.

Responses

Request samples

Content type
application/json

A submission by Acme Corp for their invoice processing AI agent.

{
  • "agent_id": "acme-invoice-processor",
  • "publisher_did": "did:example:acme123",
  • "manifest": {
    },
  • "openapi_spec": {
    }
}

Response samples

Content type
application/json
null

Usage

Retrieve Installation Usage Statistics

Uncover the journey of your connector's performance over the last 30 days. This endpoint provides an insightful peek into the success, challenges, and costs associated with your installations, ensuring you have the information needed to optimize your operations.

Responses

Response samples

Content type
application/json
null

Credential Management

Revoke a connector's credential securely

In the intricate dance of data security, credentials sometimes lose their rhythm. This endpoint lets you gracefully revoke a credential, ensuring that your organization maintains its harmony. With the power of Passport delegation, only the maestro—the org admin or credential owner—can call the shots.

Responses

Response samples

Content type
application/json
{
  • "credential_id": "cred-12345",
  • "status": "revoked",
  • "revoked_by": "passport-67890",
  • "revoked_at": "2023-10-08T14:48:00.000Z"
}

Cache

Retrieve credential cache statistics

Peel back the curtain on the performance of your credential caching system with this endpoint. Designed for system administrators, it provides a snapshot of cache efficiency, offering insights into hits, misses, and evictions. This data is crucial for optimizing the performance and reliability of your organization's credential handling.

Responses

Response samples

Content type
application/json

An example response showing typical cache statistics.

{
  • "hits": 1200,
  • "misses": 300,
  • "evictions": 50,
  • "size": 500,
  • "hit_rate": 0.8,
  • "hit_rate_percent": "80.00%"
}

Admin

Retrieve credential cache statistics

Peel back the curtain on the performance of your credential caching system with this endpoint. Designed for system administrators, it provides a snapshot of cache efficiency, offering insights into hits, misses, and evictions. This data is crucial for optimizing the performance and reliability of your organization's credential handling.

Responses

Response samples

Content type
application/json

An example response showing typical cache statistics.

{
  • "hits": 1200,
  • "misses": 300,
  • "evictions": 50,
  • "size": 500,
  • "hit_rate": 0.8,
  • "hit_rate_percent": "80.00%"
}

Retrieve Intent Activity

Explore the vibrant tapestry of activities within your organization, dynamically orchestrating human-AI interactions. This endpoint exists to empower administrators by providing a window into the AI intent landscape, allowing for data-driven insights and strategic decision-making.

Responses

Response samples

Content type
application/json

Retrieving the first page of intent activities for the 'acme' organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Performance Metrics

Retrieve AI Model Performance Metrics

Delve into the operational excellence of your AI model by retrieving performance metrics that span request volumes, success rates, latency, and cost. This endpoint empowers you to make data-driven decisions by providing insights into model efficiency over the past 30 days, dissected by complexity tiers.

Responses

Response samples

Content type
application/json

Fetches detailed performance metrics for the 'gpt-4-turbo' model, offering insights into its operational behavior.

{
  • "model_id": "gpt-4-turbo",
  • "total_requests": 1234,
  • "success_rate": 0.98,
  • "avg_latency_ms": 2500,
  • "avg_cost_usd": 0.025,
  • "by_complexity": {
    }
}

Secrets

Retrieve encrypted secret value by key

Unravel the mystery behind secure data management by retrieving a secret value tied to your organization's cryptographic identity. This endpoint leverages a KMS-backed cascade approach to ensure that your sensitive information is accessible only within the right context, providing robust security and seamless integration.

Responses

Response samples

Content type
application/json

Retrieve the secret value for the 'api-token' key within the context of the 'acme' organization.

{
  • "value": "s3cr3tV4lu3"
}

Delete Secret by Key

In the evolving landscape of digital orchestration, secrets securely guard access to sensitive operations. This endpoint empowers users to surgically delete a secret, purging it from the current scoped context. By doing so, it ensures that outdated or compromised credentials are swiftly retired, maintaining the integrity and security of the systems they protect.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Rotate a secret to a new value

Secrets are the lifeblood of secure systems, and rotating them periodically ensures their integrity. This endpoint allows you to rotate an existing secret to a new value, fortifying your security posture against potential vulnerabilities. The dual support for both new_value and newValue caters to modern and legacy clients alike, ensuring a smooth transition in your security practices.

Request Body schema: application/json
required
One of
new_value
required
string

The new secret value to replace the existing one.

Responses

Request samples

Content type
application/json
Example

Rotating a secret using the modern new_value field.

{
  • "new_value": "newSecret123!"
}

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve organization's secret keys

Embark on a journey through the vault of secrets tailored for your organization. This endpoint is your key to uncovering cryptographic treasures, filtered by an optional prefix to hone in on specific secrets. Whether you're securing data or managing credentials, this is an essential tool for orchestrating human-AI interactions with precision.

Responses

Response samples

Content type
application/json

Organization retrieves secret key names to audit credentials.

{
  • "keys": [
    ]
}

Retrieve metadata for a secret key

Unlock the insights without the secrets. This endpoint provides metadata about a secret key, offering a glimpse into its lifecycle and attributes without revealing its value. It's a crucial tool for auditing and understanding the secrets you manage, ensuring your operations maintain transparency and control.

Responses

Response samples

Content type
application/json
Example
{
  • "key": "api-key-1234",
  • "description": "Production API key for payment processing",
  • "rotatable": true,
  • "expires_at": "2025-12-31T23:59:59.000Z",
  • "created_at": "2023-01-15T12:34:56.000Z",
  • "updated_at": "2023-06-10T08:22:44.000Z"
}

Secrets Management

Create or update a secret securely

Securely store or modify a secret using a cryptographic key, with optional details like expiration and rotatability. This endpoint ensures sensitive information is safeguarded while allowing controlled access and updates, crucial for dynamic environments where secrets must be frequently rotated.

Request Body schema: application/json
required
value
required
string

The secret value to store. This is required.

description
string

Optional description of the secret's purpose

rotatable
boolean

Indicates if the secret can be rotated

expires_at
string <date-time>

The ISO 8601 date when the secret expires

expiresAt
string <date-time>

Legacy field for expiration date

Responses

Request samples

Content type
application/json

An example of an API key that can be rotated and has an expiration date.

{
  • "value": "supersecretapikey123",
  • "description": "API key for external service integration",
  • "rotatable": true,
  • "expires_at": "2024-12-31T23:59:59Z"
}

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Messages

Retrieve Approval Request Conversation History

Dive into the narrative of an approval request by accessing its conversation history. This endpoint serves to illuminate the decision-making process, showcasing interactions and deliberations that led to an approval. It supports both delegation and signed token authentication, ensuring secure access to sensitive dialogues.

Responses

Response samples

Content type
application/json
{
  • "approval_id": "12345",
  • "messages": [
    ]
}

Messaging

Send a Message in Approval Conversation

In the intricate ballet of task approvals, communication is key. This endpoint lets you send a message within an approval conversation, fostering collaboration and ensuring clarity. If the conversation doesn't exist yet, fear not—it gracefully creates one, ensuring no message goes unheard.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Deliver cross-user C2C messages securely

In the interconnected world of HUMAN, delivering messages between users is crucial. This endpoint allows users to send messages directly to another's inbox, ensuring authenticity with Ed25519 signatures. It's the lifeline for secure communication within HUMAN's vibrant ecosystem.

Request Body schema: application/json
required
message_id
required
string

Unique identifier for the message.

thread_id
string

Identifier for the conversation thread.

recipient_did
required
string

DID of the message recipient.

sender_did
required
string

DID of the message sender.

intent_kind
required
string

The type of intent this message carries.

payload
required
object

The actual content of the message.

signature
required
string

Ed25519 signature for message authentication.

created_at
required
string <date-time>

Timestamp when the message was created.

expires_at
string <date-time>

Expiration time of the message, if applicable.

Responses

Request samples

Content type
application/json

A typical message sent from one user to another, ensuring secure delivery.

{
  • "message_id": "msg-123456",
  • "thread_id": "thread-abcde",
  • "recipient_did": "did:example:recipient",
  • "sender_did": "did:example:sender",
  • "intent_kind": "inform",
  • "payload": {
    },
  • "signature": "abc123signature",
  • "created_at": "2023-10-01T14:48:00Z",
  • "expires_at": "2023-10-02T14:48:00Z"
}

Response samples

Content type
application/json
{
  • "received": true,
  • "message_id": "msg-123456"
}

Access Management

Submit access request for investor portal

Empower your leadership to manage access with confidence. This endpoint allows you to submit a request for accessing the investor portal, ensuring that all requests are vetted by organizational leaders for security and compliance.

Request Body schema: application/json
required
message
string

Optional message to accompany the access request, limited to 1000 characters.

Responses

Request samples

Content type
application/json

An example where a user provides a message explaining the reason for their access request.

{
  • "message": "Requesting access to manage investment portfolios and view real-time data insights."
}

Response samples

Content type
application/json
{
  • "id": "access-req-task-12345",
  • "status": "pending"
}

Create or Update Vault Access Grant

Orchestrate secure access to organizational vaults by creating or updating access grants. This endpoint ensures that only authenticated users can grant themselves access, reinforcing security by tying cryptographic identity to vault permissions.

Request Body schema: application/json
required
vault_entity_did
required
string

Decentralized identifier of the vault entity (organization)

member_did
required
string

Decentralized identifier of the member requesting access

encrypted_mvk
required
string

Base64-encoded encrypted master vault key

iv
required
string

Base64-encoded initialization vector (12 bytes)

Responses

Request samples

Content type
application/json

A member of Acme Corp granting themselves access to the vault

{
  • "vault_entity_did": "did:example:acme-corp",
  • "member_did": "did:example:john-doe",
  • "encrypted_mvk": "U2FsdGVkX1+abc123456=",
  • "iv": "QUJDREVGRw=="
}

Response samples

Content type
application/json
{
  • "ok": true
}

Remove a Capability Grant by ID

This endpoint allows you to delete a specific capability grant from the Capability Graph, effectively revoking a granted skill or permission. It's like removing a key from a keyring, ensuring that access is only available to those who truly need it, enhancing security and clarity in your orchestrated operations.

Responses

Response samples

Content type
application/json

Indicates successful removal of the capability grant.

{
  • "message": "Capability grant successfully deleted."
}

Investor Portal

Submit access request for investor portal

Empower your leadership to manage access with confidence. This endpoint allows you to submit a request for accessing the investor portal, ensuring that all requests are vetted by organizational leaders for security and compliance.

Request Body schema: application/json
required
message
string

Optional message to accompany the access request, limited to 1000 characters.

Responses

Request samples

Content type
application/json

An example where a user provides a message explaining the reason for their access request.

{
  • "message": "Requesting access to manage investment portfolios and view real-time data insights."
}

Response samples

Content type
application/json
{
  • "id": "access-req-task-12345",
  • "status": "pending"
}

AccessRequests

Retrieve User's Latest Access Request

In the complex dance between humans and AI, knowing the status of your access request is paramount. This endpoint grants you a window into your own access journey, revealing whether your plea for entry into the digital realm is pending, approved, or denied. Whether you're an investor checking your status or an AI ensuring compliance, this status update is your compass.

Responses

Response samples

Content type
application/json

The user has an approved access request.

{
  • "request": {
    }
}

UserStatus

Retrieve User's Latest Access Request

In the complex dance between humans and AI, knowing the status of your access request is paramount. This endpoint grants you a window into your own access journey, revealing whether your plea for entry into the digital realm is pending, approved, or denied. Whether you're an investor checking your status or an AI ensuring compliance, this status update is your compass.

Responses

Response samples

Content type
application/json

The user has an approved access request.

{
  • "request": {
    }
}

Fraud Detection

Log Fraud Decision for Provenance Tracking

In the delicate dance of fraud detection, ensuring the authenticity of decisions is paramount. This endpoint records fraud decisions into the HUMAN Distributed Ledger, providing an immutable provenance trail. By capturing these decisions, organizations can maintain transparency and accountability in their fraud detection processes.

Request Body schema: application/json
required
case_ref
required
string

Reference ID of the fraud case.

decision_type
string
Default: "fraud_decision"

Type of decision made regarding the case.

Responses

Request samples

Content type
application/json

Logs a decision for a potential fraud case.

{
  • "case_ref": "INV-12345",
  • "decision_type": "fraudulent"
}

Response samples

Content type
application/json
{
  • "provenance_entry_id": "cp_fprov_67890",
  • "case_ref": "INV-12345",
  • "decision_type": "fraudulent",
  • "recorded_at": "2023-10-01T12:00:00Z"
}

Fraud

Retrieve Fraud Metrics for Organization

Discover insights into your organization's fraud management with a comprehensive overview of fraud metrics. Use this endpoint to access key statistics, ensuring your team stays one step ahead in the fight against fraud. The metrics are meticulously calculated based on recent activities, providing both cached results for efficiency and live data for accuracy.

Responses

Response samples

Content type
application/json
{
  • "period": "30d",
  • "computed_at": "2023-10-05T14:48:00Z",
  • "source": "live_aggregate",
  • "metrics": {
    }
}

Initiate a fraud policy review

This endpoint empowers organizations to initiate a review of potential fraud activities within their systems. By submitting relevant case references, organizations can ensure a systematic and documented approach to fraud detection and mitigation. This service plays a critical role in enhancing transparency and accountability in financial transactions.

Request Body schema: application/json
required
One of
case_ref
required
string

Unique reference for the fraud case

case_id
string

Alternate identifier for the fraud case

Responses

Request samples

Content type
application/json

Initiating a fraud review using a case reference

{
  • "case_ref": "FRD-20231010-001"
}

Response samples

Content type
application/json
{
  • "review_id": "cp_fpol_123456",
  • "case_ref": "FRD-20231010-001",
  • "status": "recorded",
  • "reviewed_at": "2023-10-10T14:48:00.000Z"
}

Employee Onboarding

Initiate Employee Onboarding with Verification

Embark on a seamless journey to onboard new employees by creating their records and initiating the verification process. This endpoint empowers organizations to swiftly integrate new members into their ranks, ensuring they are equipped with a digital identity that links them securely to their workplace.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Employees

Retrieve list of organization employees

Discover the diverse talent within your organization by listing all current employees. This endpoint empowers you with the ability to manage workforce data efficiently, ensuring you can make informed decisions quickly. It's a key tool for organizations like 'acme' to maintain a dynamic understanding of their human resources landscape.

Responses

Response samples

Content type
application/json

A snapshot of the employee directory for Acme Corp, showcasing a diverse set of roles and departments.

{
  • "data": [
    ],
  • "limit": 50,
  • "cursorField": "created_at"
}

Namespace

Register a unique organization slug

Organizations claim a globally unique slug, essential for agent URI addressing, ensuring seamless namespace resolution in the HUMAN ecosystem. This process fortifies your organization's identity, carving a distinct digital path with every agent interaction.

Request Body schema: application/json
required
slug
required
string

The desired slug, must be 3-64 characters, lowercase alphanumeric with hyphens, starting and ending with an alphanumeric character.

display_name
string

Optional human-readable name for the organization.

Responses

Request samples

Content type
application/json

Claim a slug for Acme Corporation's namespace

{
  • "slug": "acme-corp",
  • "display_name": "Acme Corporation"
}

Response samples

Content type
application/json
null

Data Retrieval

Retrieve specific resource by ID or URI

Dive into the intricate world of resource management with this endpoint. Whether you possess a UUID or a URI, this call unravels the details of a singular resource, ensuring data integrity and precision in task orchestration through the HUMAN Protocol.

Responses

Response samples

Content type
application/json
{}

Examples

Retrieve an example schema payload

Dive into the world of schemas by fetching a sample payload that showcases its structure and usage. This endpoint is your gateway to creating realistic mock data, enhancing SDK documentation, and enriching your development playground with practical examples.

Responses

Response samples

Content type
application/json

An example payload for the core.email.message.v1 schema, perfect for testing email processing in your application.

{
  • "schema_id": "core.email.message.v1",
  • "kind": "message",
  • "version": "1.0",
  • "example": {
    }
}

Context

Record Passport Travel Context

Embark on a journey of seamless orchestration between humans and AI. This endpoint securely logs the travel context of a Passport within an organization, ensuring that each step is accounted for with precision and trust.

Request Body schema: application/json
required
passport_did
required
string

The decentralized identifier for the Passport

object

Additional context data related to the travel

Responses

Request samples

Content type
application/json

Record context for a Passport traveling to Acme Corporation's headquarters.

{
  • "passport_did": "did:example:123456789abcdefghi",
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "context_id": "cp_travel_001",
  • "passport_did": "did:example:123456789abcdefghi",
  • "recorded_at": "2023-10-01T12:00:00Z"
}

Merchant

Whitelist merchants for passport interactions

Enlist merchants to interact with a passport holder, ensuring trusted exchanges within the HUMAN ecosystem. This process empowers organizations to manage merchant relationships securely and efficiently, leveraging cryptographic identities.

Request Body schema: application/json
required
passport_did
required
string

Decentralized Identifier for the passport holder

merchant_id
required
string

Unique identifier for the merchant

Responses

Request samples

Content type
application/json

An example of whitelisting a merchant for a passport holder

{
  • "passport_did": "did:human:123456789abcdefghi",
  • "merchant_id": "merchant_987654321"
}

Response samples

Content type
application/json
null

Vault

Export encrypted documents from vault

Unveil the cryptic treasures stored within your vault by exporting encrypted documents tied to an entity's cryptographic identity. This endpoint empowers organizations, like 'acme', to effortlessly migrate their secured data while maintaining the sanctity of their information.

Responses

Response samples

Content type
application/json

Example of successfully exporting documents for an entity.

{
  • "documents": [
    ]
}

Migrate encrypted documents into vault

Unlock the power of secure document storage by migrating encrypted data into the HUMAN vault. This process ensures that your data remains protected and easily accessible, maintaining integrity through our distributed ledger.

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json

Migrating a batch of encrypted invoices for the 'acme' organization

{
  • "documents": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "completed",
  • "inserted": 1,
  • "total": 1
}

Migrate Documents Between Vaults

Embark on a journey to securely migrate your documents from one vault to another, ensuring data integrity and provenance tracking. This endpoint empowers organizations to seamlessly transition their data to a new storage destination, enhancing operational flexibility and resilience.

Request Body schema: application/json
required
target_connector_id
required
string

Identifier of the target connector, e.g., 'human-cloud-vault'.

target_endpoint
required
string

Base URL of the target vault API, e.g., 'https://api.example.com/v1/vault'.

target_token
string

Authorization token for the target vault. Optional if provided in the Authorization header.

dry_run
boolean

When true, simulates migration without actual data transfer.

Responses

Request samples

Content type
application/json

Migrate documents to Acme Corp's vault with a dry run.

{}

Response samples

Content type
application/json
{
  • "status": "completed",
  • "migrated": 42,
  • "message": "Documents migrated successfully."
}

Retrieve Organization Vault Access Grant

Fetches the encrypted master vault key (MVK) for a specific organization. This endpoint empowers human agents to securely access their organization's data vault by retrieving a cryptographically secure key, ensuring both access and privacy.

Responses

Response samples

Content type
application/json

An agent retrieves their organization's encrypted master vault key for secure operations.

{
  • "encrypted_mvk": "Q2hhcmxlc1RpbWVzVGhlQmVzdE9mVGltZXM=",
  • "iv": "c2VjdXJlSW5pdFZlY3Rvcg==",
  • "created_at": "2023-10-01T12:34:56Z"
}

Store Encrypted Document Securely

Embark on a journey of secure document storage with our vault endpoint. This API endpoint enables you to safely store encrypted documents, ensuring that sensitive data is guarded with precision. By using a cryptographic identity, it maintains integrity and traceability, making it indispensable for organizations like 'acme' that require robust data protection.

Request Body schema: application/json
required
ciphertext
required
string

The encrypted document content, encoded in base64.

iv
required
string

The initialization vector for the encryption, encoded in base64 and must decode to 12 bytes.

object

Optional metadata; each value is arbitrary JSON (Record<string, unknown>) stored as JSONB — not limited to strings.

Responses

Request samples

Content type
application/json

An example of storing an encrypted invoice document.

{
  • "ciphertext": "c3VwZXJzZWNyZXRjb250ZW50",
  • "iv": "dGVzdGluaXQxMjM=",
  • "metadata": {
    }
}

Response samples

Content type
application/json
null

Retrieve vault document metadata

Explore the labyrinth of your digital vault by retrieving only the metadata of documents within a specified collection. This endpoint empowers you to efficiently navigate and manage your document collections without exposing sensitive details.

Responses

Response samples

Content type
application/json

An example response showing metadata for documents in a vault collection.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Retrieve an encrypted document from vault

This endpoint dives into the depths of the HUMAN vault to retrieve an encrypted document, ensuring secure data retrieval for your organization. It exists to seamlessly bridge the gap between secure storage and access, allowing authorized users to fetch their critical documents without compromising on security.

Responses

Response samples

Content type
application/json

Retrieving an encrypted document for invoice processing in the Acme organization.

{
  • "ciphertext": "c29tZSBlbmNvZGVkIGNpcGhlcnRleHQ=",
  • "iv": "ZGVtb25zdHJhdGlvbml2",
  • "metadata": {
    },
  • "wrapped_keys": [ ],
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-15T12:00:00Z"
}

Remove a document from the vault

In the HUMAN ecosystem, deleting a document is akin to erasing a chapter from a ledger. This endpoint allows users to surgically remove artifacts from their vault, ensuring that only the most relevant data persists, thus maintaining a pristine and efficient data environment.

Responses

Response samples

Content type
application/json

Illustrates a successful delete operation where the document is removed from the vault.

null

Share Access to Vault Document

Empower collaboration by securely sharing access to a vault document with another entity. This endpoint ensures that data sharing is both secure and traceable, leveraging the HUMAN platform's cryptographic identity and provenance tracking.

Request Body schema: application/json
required
recipient_did
required
string

Decentralized Identifier of the recipient entity.

wrapped_dek
required
string

Base64-encoded wrapped Data Encryption Key for secure document access.

expires_at
string <date-time>

Optional expiration date and time for the shared access.

Responses

Request samples

Content type
application/json

Sharing document access with a recipient using a wrapped encryption key.

{
  • "recipient_did": "did:human:123abc",
  • "wrapped_dek": "U2FsdGVkX1+E5V5bW7b5==",
  • "expires_at": "2024-12-31T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "doc_id": "doc1234"
}

Revoke Document Sharing with Recipient

In the tapestry of digital collaboration, sharing is key, but sometimes ties need to be severed. This endpoint allows you to revoke access to a document for a specific recipient, ensuring only the right eyes see your data. It's a safeguard for when sharing needs to be undone without a trace.

Responses

Response samples

Content type
application/json

Revoking document share for recipient with a valid request.

{
  • "ok": true,
  • "doc_id": "123e4567-e89b-12d3-a456-426614174000"
}

Retrieve documents shared with user

Uncover the vault documents that others have explicitly shared with you. This endpoint empowers the authenticated user by listing shared documents, ensuring you're always in the know. Ideal for collaboration and transparency, it securely returns metadata, omitting encrypted content, and handles pagination gracefully.

Responses

Response samples

Content type
application/json

A list of documents shared with a user from the 'acme' organization.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

DataMigration

Export encrypted documents from vault

Unveil the cryptic treasures stored within your vault by exporting encrypted documents tied to an entity's cryptographic identity. This endpoint empowers organizations, like 'acme', to effortlessly migrate their secured data while maintaining the sanctity of their information.

Responses

Response samples

Content type
application/json

Example of successfully exporting documents for an entity.

{
  • "documents": [
    ]
}

Migration

Migrate encrypted documents into vault

Unlock the power of secure document storage by migrating encrypted data into the HUMAN vault. This process ensures that your data remains protected and easily accessible, maintaining integrity through our distributed ledger.

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json

Migrating a batch of encrypted invoices for the 'acme' organization

{
  • "documents": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "completed",
  • "inserted": 1,
  • "total": 1
}

Migrate Documents Between Vaults

Embark on a journey to securely migrate your documents from one vault to another, ensuring data integrity and provenance tracking. This endpoint empowers organizations to seamlessly transition their data to a new storage destination, enhancing operational flexibility and resilience.

Request Body schema: application/json
required
target_connector_id
required
string

Identifier of the target connector, e.g., 'human-cloud-vault'.

target_endpoint
required
string

Base URL of the target vault API, e.g., 'https://api.example.com/v1/vault'.

target_token
string

Authorization token for the target vault. Optional if provided in the Authorization header.

dry_run
boolean

When true, simulates migration without actual data transfer.

Responses

Request samples

Content type
application/json

Migrate documents to Acme Corp's vault with a dry run.

{}

Response samples

Content type
application/json
{
  • "status": "completed",
  • "migrated": 42,
  • "message": "Documents migrated successfully."
}

Retrieve workflow migration status

Delve into the lifecycle of your workflow as it transitions through updates. This endpoint provides insights into the current migration status, ensuring that your operations remain seamless and informed.

Responses

Response samples

Content type
application/json

An example showing a completed migration status for a workflow.

{
  • "status": "completed",
  • "details": "The workflow migration completed successfully without any issues."
}

Preview migration of workflows and agents

Embark on a journey to modernize your workflows effortlessly with this endpoint. By analyzing the structure and components of your intended migration, it offers insights into potential steps, prompts, and warnings, all while ensuring no data is prematurely committed. This vital preview phase helps you make informed decisions before taking the plunge with POST /import.

Request Body schema: application/json
required
platform
required
string

The target platform for migration.

required
object

Details of the workflow to be migrated.

Responses

Request samples

Content type
application/json

A simple workflow migration to the 'acme' platform.

{
  • "platform": "acme",
  • "workflow": {
    }
}

Response samples

Content type
application/json
{
  • "stats": {
    },
  • "steps": [
    ],
  • "prompts": [
    ],
  • "warnings": [
    ]
}

AccessControl

Retrieve Organization Vault Access Grant

Fetches the encrypted master vault key (MVK) for a specific organization. This endpoint empowers human agents to securely access their organization's data vault by retrieving a cryptographically secure key, ensuring both access and privacy.

Responses

Response samples

Content type
application/json

An agent retrieves their organization's encrypted master vault key for secure operations.

{
  • "encrypted_mvk": "Q2hhcmxlc1RpbWVzVGhlQmVzdE9mVGltZXM=",
  • "iv": "c2VjdXJlSW5pdFZlY3Rvcg==",
  • "created_at": "2023-10-01T12:34:56Z"
}

Retrieve accessible knowledge base documents

Unleash the full potential of your organization's knowledge by accessing documents curated to your session's security clearance. This endpoint provides a tailored list of knowledge base entries, ensuring that every piece of information you view aligns with your classification tier, be it public or internal. Harnessing the HUMAN protocol, it empowers MCP resource listings with precision and safety.

Responses

Response samples

Content type
application/json

Shows retrieval of internal documents for Acme Corp.

{
  • "items": [
    ],
  • "total": 2,
  • "classification_ceiling": "Internal"
}

Documents

Retrieve vault document metadata

Explore the labyrinth of your digital vault by retrieving only the metadata of documents within a specified collection. This endpoint empowers you to efficiently navigate and manage your document collections without exposing sensitive details.

Responses

Response samples

Content type
application/json

An example response showing metadata for documents in a vault collection.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Retrieve an encrypted document from vault

This endpoint dives into the depths of the HUMAN vault to retrieve an encrypted document, ensuring secure data retrieval for your organization. It exists to seamlessly bridge the gap between secure storage and access, allowing authorized users to fetch their critical documents without compromising on security.

Responses

Response samples

Content type
application/json

Retrieving an encrypted document for invoice processing in the Acme organization.

{
  • "ciphertext": "c29tZSBlbmNvZGVkIGNpcGhlcnRleHQ=",
  • "iv": "ZGVtb25zdHJhdGlvbml2",
  • "metadata": {
    },
  • "wrapped_keys": [ ],
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-15T12:00:00Z"
}

Retrieve Knowledge Base Documents

This endpoint unveils the curated tapestry of documents within your knowledge base, meticulously orchestrated to balance access with governance. Imagine delving into a library where every book is tailored to your unique Passport — this is your gateway.

Responses

Response samples

Content type
application/json

A list of documents accessible to the user with 'Internal' classification.

{
  • "documents": [
    ]
}

Sharing

Share Access to Vault Document

Empower collaboration by securely sharing access to a vault document with another entity. This endpoint ensures that data sharing is both secure and traceable, leveraging the HUMAN platform's cryptographic identity and provenance tracking.

Request Body schema: application/json
required
recipient_did
required
string

Decentralized Identifier of the recipient entity.

wrapped_dek
required
string

Base64-encoded wrapped Data Encryption Key for secure document access.

expires_at
string <date-time>

Optional expiration date and time for the shared access.

Responses

Request samples

Content type
application/json

Sharing document access with a recipient using a wrapped encryption key.

{
  • "recipient_did": "did:human:123abc",
  • "wrapped_dek": "U2FsdGVkX1+E5V5bW7b5==",
  • "expires_at": "2024-12-31T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "doc_id": "doc1234"
}

Event Management

Ingest Event Data with Verification

Harness the power of Human-AI orchestration by securely ingesting event data into the HUMAN platform. This endpoint ensures data integrity through signature verification and timestamps, safeguarding against replay attacks and unauthorized access.

Request Body schema: application/json
required
event_type
required
string

The type of event, formatted in dot-notation lowercase (e.g., billing.invoice.paid)

source_connector_id
required
string

Identifier of the source connector sending the event

raw_payload
required
object

The raw data payload of the event

normalized_payload
object

The normalized version of the event data, if applicable

source_did
string

Decentralized identifier of the source

delegation_chain
Array of strings

Chain of delegations for authorization

subject
string

The subject or entity to which the event pertains

string or integer

The timestamp of the event in ISO 8601 or Unix seconds

verification_status
string

The verification status as asserted by the connector

Responses

Request samples

Content type
application/json

An event representing a paid invoice from the 'acme' organization

{
  • "event_type": "billing.invoice.paid",
  • "source_connector_id": "acme_invoice_system",
  • "raw_payload": {
    },
  • "event_timestamp": "2023-10-10T14:48:00Z"
}

Response samples

Content type
application/json
{
  • "event_id": "123e4567-e89b-12d3-a456-426614174000",
  • "content_hash": "abc123xyz789",
  • "created_at": "2023-10-10T14:48:00Z"
}

Data Ingestion

Ingest Event Data with Verification

Harness the power of Human-AI orchestration by securely ingesting event data into the HUMAN platform. This endpoint ensures data integrity through signature verification and timestamps, safeguarding against replay attacks and unauthorized access.

Request Body schema: application/json
required
event_type
required
string

The type of event, formatted in dot-notation lowercase (e.g., billing.invoice.paid)

source_connector_id
required
string

Identifier of the source connector sending the event

raw_payload
required
object

The raw data payload of the event

normalized_payload
object

The normalized version of the event data, if applicable

source_did
string

Decentralized identifier of the source

delegation_chain
Array of strings

Chain of delegations for authorization

subject
string

The subject or entity to which the event pertains

string or integer

The timestamp of the event in ISO 8601 or Unix seconds

verification_status
string

The verification status as asserted by the connector

Responses

Request samples

Content type
application/json

An event representing a paid invoice from the 'acme' organization

{
  • "event_type": "billing.invoice.paid",
  • "source_connector_id": "acme_invoice_system",
  • "raw_payload": {
    },
  • "event_timestamp": "2023-10-10T14:48:00Z"
}

Response samples

Content type
application/json
{
  • "event_id": "123e4567-e89b-12d3-a456-426614174000",
  • "content_hash": "abc123xyz789",
  • "created_at": "2023-10-10T14:48:00Z"
}

Logging

Emit and log an event in the system

This endpoint allows the orchestration of human and AI interactions by emitting events that are securely logged and tracked. It ensures the integrity and provenance of actions within the HUMAN protocol by leveraging cryptographic proofs and distributed ledger technology. This guarantees transparency and trust in the interactions processed by the platform.

Request Body schema: application/json
required
event_type
required
string

The type of event being emitted. This is a required field.

payload
object

Arbitrary JSON object containing details relevant to the event.

subject
string

The subject related to this event, often a DID or other identifier.

emitter_agent_did
string

The DID of the agent emitting the event; if provided, the event will be signed.

Responses

Request samples

Content type
application/json

An event indicating an invoice has been processed by an agent within the 'acme' organization.

{
  • "event_type": "invoice.processed",
  • "payload": {
    },
  • "subject": "did:example:123456789",
  • "emitter_agent_did": "did:example:agent:acme"
}

Response samples

Content type
application/json
{
  • "event_id": "evt-5f6a3b4d2e7c",
  • "content_hash": "abc123def456",
  • "signed": true,
  • "created_at": "2023-10-01T12:34:56Z"
}

Subscriptions

Subscribe to Webhook Events for Your Organization

Imagine receiving only the events that matter most to your organization, seamlessly and securely. This endpoint allows you to subscribe to webhook events, ensuring your systems are always in sync with the latest updates from the HUMAN platform. It's designed for organizations looking to automate and streamline their workflows with precision.

Request Body schema: application/json
required
event_pattern
required
string

The pattern of events to subscribe to, using dot-notation.

target_url
required
string <uri>

The destination URL where events will be delivered.

signing_secret
string

Optional secret for signing webhook requests.

source_filter
string

Optional filter for the event source.

observability_profile
string

Profile ID for observability settings.

metadata
object

Additional metadata for the subscription.

audience
string
Enum: "tenant_safe" "platform_internal"

Defines who the subscription is intended for.

Responses

Request samples

Content type
application/json

Acme Corp subscribing to all billing invoice events.

{
  • "event_pattern": "billing.invoice.*",
  • "target_url": "https://webhooks.acme.com/events",
  • "signing_secret": "supersecret",
  • "metadata": {
    },
  • "audience": "tenant_safe"
}

Response samples

Content type
application/json

Response when Acme Corp successfully subscribes to webhook events.

{
  • "subscription_id": "sub-12345",
  • "event_pattern": "billing.invoice.*",
  • "target_url": "https://webhooks.acme.com/events",
  • "signing_secret_provided": true,
  • "metadata": {
    }
}

Retrieve active webhook subscriptions

This endpoint lets you explore the landscape of webhook subscriptions tied to your organization. By calling it, you can discover which events you're tracking in real-time, ensuring your applications remain in sync with the heartbeat of your business.

Responses

Response samples

Content type
application/json

A response showing active webhook subscriptions for a specific organization.

{
  • "data": [
    ],
  • "hasMore": false,
  • "limit": 2,
  • "cursor": "opaqueCursor123"
}

Retrieve webhook subscription details

Unlock the secrets of your organization's data flow by retrieving the details of a webhook subscription. This endpoint illuminates the path for authorized users to inspect the subscriptions tied to their cryptographic identity, ensuring data harmony between systems.

Responses

Response samples

Content type
application/json

Fetching details of a webhook subscription for Acme Corporation.

{}

Deactivate a webhook subscription

Effortlessly manage webhook subscriptions by deactivating them without losing valuable delivery history. This endpoint allows organizations to gracefully retire subscriptions, ensuring continuity and integrity of past interactions.

Responses

Response samples

Content type
application/json

An example of successfully deactivating a subscription for an organization.

{
  • "subscription_id": "sub-12345",
  • "active": false,
  • "deactivated_at": "2023-10-01T12:34:56Z"
}

Retrieve webhook delivery history

This endpoint unveils the rich tapestry of webhook deliveries for a specific subscription, providing insight into the lifecycle and status of each delivery attempt. Whether you're troubleshooting a missing event or analyzing delivery performance, this endpoint offers a transparent view into your webhook ecosystem.

Responses

Response samples

Content type
application/json

Retrieve deliveries for subscription 'sub_1234' with a comprehensive view of each delivery's status.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursor": "opaque_cursor_string",
  • "hasMore": false,
  • "queue_summary": {
    }
}

Subscribe to Companion Events

Empower your organization with dynamic event subscriptions, seamlessly connecting your AI and human capabilities. The endpoint crafts a bridge between your systems and Companion, fostering intelligent task orchestration.

Request Body schema: application/json
required
event_pattern
required
string

A pattern that matches the events to subscribe to.

source_connector_id
string

Identifier for the source connector related to the event.

label
string

An optional label to identify the subscription.

Responses

Request samples

Content type
application/json

Subscribe to invoice processing events from a specific source.

{
  • "event_pattern": "invoice.*",
  • "source_connector_id": "acme_finance_connector",
  • "label": "Invoice Subscription"
}

Response samples

Content type
application/json
{
  • "subscription_id": "sub-1234567890",
  • "event_pattern": "invoice.*",
  • "source_connector_id": "acme_finance_connector",
  • "label": "Invoice Subscription",
  • "created_at": "2023-10-15T12:34:56Z"
}

Retrieve active agent-trigger subscriptions

Dive into the orchestration of AI and human tasks by exploring the active subscriptions for agent-triggered events. This endpoint illuminates the path of notifications as they journey through the HUMAN ecosystem, ensuring tasks are efficiently routed and executed.

Responses

Response samples

Content type
application/json

Acme Corp's agent-triggered subscriptions for their invoice processing workflow.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Versioning

Retrieve the active version of a prompt

In the dynamic world of prompts, accessing the latest version is crucial for keeping your applications in sync. This endpoint allows you to retrieve the active version of a specific prompt, ensuring that you are always working with the most current information. It supports both short keys and full URIs, making it versatile for various use cases.

Responses

Response samples

Content type
application/json

Retrieves the active version details for a prompt with a short key.

{
  • "version": "v2.3.1",
  • "content": "Welcome to the new era of AI-driven orchestration."
}

Retrieve a specific prompt version

Uncover the rich history of your creative assets by retrieving a specific version of a prompt. This endpoint exists to empower organizations to track their content evolution, ensuring that every iteration is preserved and accessible for future reference.

Responses

Response samples

Content type
application/json
null

Retrieve paginated canvas version history

Explore the rich tapestry of your canvas's evolution with this endpoint. Designed for those who seek to understand the journey of their creations, it provides a paginated list of all versions. Dive deep into the past and see how your ideas have transformed over time.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 2,
  • "hasMore": true,
  • "cursorField": "version"
}

Version Management

Retrieve versions of a specific prompt

Explore the evolutionary journey of your prompts by listing all their versions. This endpoint empowers organizations to track changes, ensuring clarity and accountability in modifications over time. Whether for audit purposes or creative exploration, understanding the version history is pivotal.

Responses

Response samples

Content type
application/json

A detailed look at all versions of the 'invoice-processing' prompt.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "version",
  • "totalCount": 2
}

Deprecate a specific prompt version

This endpoint allows you to mark a specific version of a prompt as deprecated. It plays a crucial role in maintaining the integrity of your prompts' lifecycle, ensuring that outdated or incorrect versions are no longer in active use. By deprecating a version, you safeguard the quality and consistency of tasks processed by your organization.

Responses

Response samples

Content type
application/json

A prompt version is successfully deprecated.

{
  • "prompt_uri": "prompt://acme/invoice-processing",
  • "version": "v1.2.3",
  • "status": "deprecated",
  • "deprecated_at": "2023-11-02T14:30:00Z"
}

Publishing

Publish a new version of a prompt

Publishing prompts is at the heart of dynamic content orchestration within HUMAN. This endpoint allows you to release updates, ensuring your AI tasks are fueled with the latest and greatest instructions. It's not just about updates; it's about enhancing the AI-human collaboration with precision and clarity.

Request Body schema: application/json
required
version
required
string

Semantic version of the prompt, e.g., '1.0.0'.

content
required
string

The core text or body of the prompt.

meta
required
object

Metadata about the prompt, such as namespace and ID.

input_schema
object

Optional schema detailing expected input structure.

Responses

Request samples

Content type
application/json

Publishing the first version of a new prompt for the 'acme' organization.

{
  • "version": "1.0.0",
  • "content": "Welcome to the Acme AI platform!",
  • "meta": {
    },
  • "input_schema": {
    }
}

Response samples

Content type
application/json
null

Publish a workflow for organization

This endpoint breathes life into a workflow by publishing it within the HUMAN platform. It ensures readiness, transitions the workflow state, and opens the door to new possibilities for organizational or personal use.

Request Body schema: application/json
required
scope
required
string
Enum: "personal" "workspace" "org"

Defines the level at which the workflow will be visible upon publishing.

Responses

Request samples

Content type
application/json

Publishing a workflow to make it available across the workspace.

{
  • "scope": "workspace"
}

Response samples

Content type
application/json
{
  • "workflow": {
    },
  • "warnings": [ ],
  • "marketplace_note": null
}

Prompt Management

Revert prompt to a previous version

In the fast-paced world of AI-driven tasks, mistakes happen. This endpoint allows you to gracefully roll back a prompt to a previous version, ensuring that your workflows remain consistent and reliable. By using this feature, you can swiftly mitigate issues caused by unintended changes.

Request Body schema: application/json
required
target_version
required
string

The semantic version identifier of the target version.

Responses

Request samples

Content type
application/json

This example demonstrates rolling back a prompt to version 1.3.2.

{
  • "target_version": "1.3.2"
}

Response samples

Content type
application/json
null

Version Control

Revert prompt to a previous version

In the fast-paced world of AI-driven tasks, mistakes happen. This endpoint allows you to gracefully roll back a prompt to a previous version, ensuring that your workflows remain consistent and reliable. By using this feature, you can swiftly mitigate issues caused by unintended changes.

Request Body schema: application/json
required
target_version
required
string

The semantic version identifier of the target version.

Responses

Request samples

Content type
application/json

This example demonstrates rolling back a prompt to version 1.3.2.

{
  • "target_version": "1.3.2"
}

Response samples

Content type
application/json
null

Rollback an Agent to Previous Version

This endpoint allows you to roll back an agent to a previous version, providing a safety net for deployments. However, as of now, it's a blueprint for future capabilities, reminding us that the past isn't just a place—it’s a stepping stone.

Request Body schema: application/json
required
target_version
required
string

The version to which the agent should be rolled back, e.g., '1.2.2'.

reason
string

Optional reason for the rollback, providing context for future reference.

Responses

Request samples

Content type
application/json

This example demonstrates rolling back an agent to version 1.2.2 due to a critical bug discovered in the current version.

{
  • "target_version": "1.2.2",
  • "reason": "Critical bug in current version"
}

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Performance

Retrieve Prompt Performance Snapshot

Dive into the details of how your prompts are performing with our telemetry data. This endpoint allows you to understand the efficiency, cost, and success of prompt executions, empowering you to optimize for better outcomes.

Responses

Response samples

Content type
application/json

A performance snapshot for Acme Corp's invoice processing prompt over the last week.

{
  • "prompt_key": "acme_invoice_processor",
  • "window": {
    },
  • "stats": {
    },
  • "model_breakdown": [
    ],
  • "recommended_model": "GPT-3"
}

Retrieve agent performance metrics

Discover how an agent has been performing over time, tracked by audit events. This endpoint helps organizations analyze AI agent activity to ensure efficient task handling and compliance with operational standards.

Responses

Response samples

Content type
application/json

Performance metrics for agent 'agent123' over the past 30 days.

{
  • "agent_id": "agent123",
  • "period": "30d",
  • "events_recorded": 150,
  • "rollup": "audit_payload_agent_id"
}

Telemetry

Retrieve Prompt Performance Snapshot

Dive into the details of how your prompts are performing with our telemetry data. This endpoint allows you to understand the efficiency, cost, and success of prompt executions, empowering you to optimize for better outcomes.

Responses

Response samples

Content type
application/json

A performance snapshot for Acme Corp's invoice processing prompt over the last week.

{
  • "prompt_key": "acme_invoice_processor",
  • "window": {
    },
  • "stats": {
    },
  • "model_breakdown": [
    ],
  • "recommended_model": "GPT-3"
}

Emit Tenant-Safe Telemetry Events

Harness the power of telemetry by securely emitting tenant-specific events into the HUMAN platform's telemetry bus. This endpoint facilitates the tracking of diverse activities within an organization, empowering informed decision-making and AI orchestration.

Request Body schema: application/json
required
event_type
required
string

The type of event being recorded, e.g., 'invoice_processed'.

payload
object

Additional data related to the event, allowing for context-rich telemetry.

subject
string

An optional subject identifier related to the event, such as a user ID.

idempotency_key
string

A unique key to ensure idempotency of event emission.

emitter_agent_did
required
string

DID of the agent emitting this event. Can be inferred from delegation constraints.

Responses

Request samples

Content type
application/json

Example showing a telemetry event for an invoice processing action.

{
  • "event_type": "invoice_processed",
  • "payload": {
    },
  • "subject": "user-6789",
  • "idempotency_key": "key-unique-001",
  • "emitter_agent_did": "did:example:agent123"
}

Response samples

Content type
application/json
{
  • "event_id": "evt-98765",
  • "created_at": "2023-10-12T07:20:50.52Z"
}

PromptAnalysis

Retrieve prompt model affinity insights

Dive into the nuanced world of AI model performance with this endpoint, providing insights into which models excel with a specific prompt. By analyzing historical data, it helps you orchestrate the perfect harmony between human and AI, optimizing task efficiency.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "model_id"
}

ModelPerformance

Retrieve prompt model affinity insights

Dive into the nuanced world of AI model performance with this endpoint, providing insights into which models excel with a specific prompt. By analyzing historical data, it helps you orchestrate the perfect harmony between human and AI, optimizing task efficiency.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "model_id"
}

Duplex Communication

Initiate a Duplex Session for Interaction

Begin an interactive session where human and AI collaborate seamlessly. This endpoint is the gateway to orchestrating dynamic conversations, ensuring that tasks are handled with precision and AI safety. Dive into a world where your AI can act as a passive observer, a collaborative coach, or take the reins as an active participant.

Request Body schema: application/json
required
mode
required
string
Enum: "passive" "coach" "active"

The operational mode of the session.

agent_id
string

Unique identifier for the agent initiating the session.

provider
string

Specifies the service provider for the session.

persona_id
string

Identifier for the persona to be used.

privacy_profile_id
string

Identifier for the privacy profile to be used.

org_id
string

Identifier for the organization under which the session is being initiated.

Responses

Request samples

Content type
application/json

Initiates a session with the AI in passive mode.

{
  • "mode": "passive",
  • "agent_id": "agent_007",
  • "provider": "acme_voice_service",
  • "persona_id": "support_bot",
  • "privacy_profile_id": "confidential",
  • "org_id": "acme_corp"
}

Response samples

Content type
application/json
{
  • "session_id": "sess_12345",
  • "mode": "passive",
  • "provider": "acme_voice_service",
  • "status": "active",
  • "created_at": "2023-10-01T12:34:56Z"
}

Resume an existing duplex session

In the dynamic world of human-AI collaboration, the ability to pause and resume interactions is essential. This endpoint breathes life back into a paused duplex session, allowing humans and AI to seamlessly continue their orchestration journey. By reactivating a session, we ensure that no valuable interaction goes unfinished.

Responses

Response samples

Content type
application/json
null

Interaction

Retrieve active duplex session list

This endpoint unveils the heartbeat of the HUMAN platform by listing all active duplex sessions. Imagine a bustling command center where human and AI agents collaborate seamlessly—this endpoint ensures you have a real-time view of those dynamic interactions.

Responses

Response samples

Content type
application/json

A glimpse into Acme Corp's active sessions where human and AI agents are collaboratively processing invoices.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Stop an active duplex session

In the dynamic world of real-time interactions, there comes a moment when a conversation must gracefully conclude. This endpoint empowers you to end an active duplex session, ensuring resources are efficiently reallocated and tasks can progress seamlessly. It's not just about stopping; it's about orchestrating a smooth transition.

Responses

Response samples

Content type
application/json

A successful response indicating the duplex session has been stopped.

{
  • "session_id": "123e4567-e89b-12d3-a456-426614174000",
  • "status": "stopped"
}

Initiate agent speech in a session

In the dynamic dance of human and AI collaboration, this endpoint empowers agents to vocalize within an ongoing duplex session. It's the bridge where AI articulation meets human context, enabling seamless task progression and richer interactions.

Request Body schema: application/json
required
text
required
string

The text content the agent should vocalize.

style
string
Enum: "default" "whisper" "emphasis"

The vocal style in which the text should be spoken.

interrupt_current
boolean

Determines if the current speech should be interrupted for this new speech.

Responses

Request samples

Content type
application/json

An agent in the Acme organization processes invoices and provides feedback via speech in an ongoing session.

{
  • "text": "Processing invoice #12345 for client XYZ.",
  • "style": "default",
  • "interrupt_current": true
}

Response samples

Content type
application/json
{
  • "session_id": "session-42",
  • "sent": true
}

Pause a live duplex session

In the bustling world of human-AI interaction, sometimes you need a breather. This endpoint lets you pause an ongoing duplex session, providing control and flexibility in managing real-time exchanges. Whether you're handling a complex negotiation or need a moment to regroup, this functionality ensures you can pause without missing a beat.

Request Body schema: application/json
required
session_id
required
string

Unique identifier for the duplex session to pause.

Responses

Request samples

Content type
application/json

Pausing a session with ID '123e4567-e89b-12d3-a456-426614174000'.

{
  • "session_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
null

Duplex

Retrieve active duplex session list

This endpoint unveils the heartbeat of the HUMAN platform by listing all active duplex sessions. Imagine a bustling command center where human and AI agents collaborate seamlessly—this endpoint ensures you have a real-time view of those dynamic interactions.

Responses

Response samples

Content type
application/json

A glimpse into Acme Corp's active sessions where human and AI agents are collaboratively processing invoices.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Duplex Sessions

Stop an active duplex session

In the dynamic world of real-time interactions, there comes a moment when a conversation must gracefully conclude. This endpoint empowers you to end an active duplex session, ensuring resources are efficiently reallocated and tasks can progress seamlessly. It's not just about stopping; it's about orchestrating a smooth transition.

Responses

Response samples

Content type
application/json

A successful response indicating the duplex session has been stopped.

{
  • "session_id": "123e4567-e89b-12d3-a456-426614174000",
  • "status": "stopped"
}

DuplexSession

Initiate agent speech in a session

In the dynamic dance of human and AI collaboration, this endpoint empowers agents to vocalize within an ongoing duplex session. It's the bridge where AI articulation meets human context, enabling seamless task progression and richer interactions.

Request Body schema: application/json
required
text
required
string

The text content the agent should vocalize.

style
string
Enum: "default" "whisper" "emphasis"

The vocal style in which the text should be spoken.

interrupt_current
boolean

Determines if the current speech should be interrupted for this new speech.

Responses

Request samples

Content type
application/json

An agent in the Acme organization processes invoices and provides feedback via speech in an ongoing session.

{
  • "text": "Processing invoice #12345 for client XYZ.",
  • "style": "default",
  • "interrupt_current": true
}

Response samples

Content type
application/json
{
  • "session_id": "session-42",
  • "sent": true
}

Initiate backchannel in duplex session

Open a direct communication channel with the AI agent during an active duplex session. This endpoint allows human operators to signal their current interaction mode, enhancing the coordination and effectiveness of the AI's response.

Request Body schema: application/json
required
style
required
string
Enum: "ack" "thinking"

The style of interaction: 'ack' for acknowledgment or 'thinking' for processing state.

Responses

Request samples

Content type
application/json

Signals the AI to acknowledge receipt of information.

{
  • "style": "ack"
}

Response samples

Content type
application/json
{
  • "session_id": "123456",
  • "sent": true
}

Opportunities

Discover Open Opportunities Effortlessly

Unlock a world of possibilities with our marketplace-style discovery endpoint. This tool connects organizations with open opportunities tailored to specific locations and capabilities, ensuring the right skills meet the right needs in real-time.

Responses

Response samples

Content type
application/json
{
  • "location": "USA",
  • "capability": "capability://data-entry",
  • "opportunities": [
    ]
}

Muscles

Retrieve organization's installed muscles

In the heart of the HUMAN platform, organizations harness the power of 'muscles'—modular skills to augment human capabilities. This endpoint allows you to explore the muscles currently installed for a specific organization, enabling you to manage and optimize skill resources. Delve into the dynamic world of skill orchestration, where AI and human skills converge.

Responses

Response samples

Content type
application/json

An overview of muscles installed in Acme Corp, showcasing active skill modules.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "installed_at",
  • "hasMore": false
}

Install a new muscle for an organization

In the ever-evolving orchestration of human and AI, installing a 'muscle' represents empowering your organization with new capabilities. This endpoint ensures your organization is equipped with the right tools, validating asset and version, and securing the necessary connectors for a seamless integration.

Request Body schema: application/json
required
muscle_id
required
string

Unique identifier in publisher.name format.

version
required
string

Semantic version of the muscle being installed.

asset_id
string

Optional ID of the marketplace asset if specifying an asset.

config
object

Configuration settings for the muscle.

Responses

Request samples

Content type
application/json

Installing the spreadsheet processing muscle for data analytics.

{
  • "muscle_id": "human.spreadsheets",
  • "version": "1.0.0",
  • "asset_id": "asset-1234",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "org_did": "did:human:org:acme",
  • "muscle_id": "human.spreadsheets",
  • "version_installed": "1.0.0",
  • "asset_id": "asset-1234",
  • "config": {
    },
  • "installed_by_did": "did:human:agent:installer",
  • "status": "active"
}

Upgrade an installed muscle version

In the dynamic world of AI-powered organizations, keeping your capabilities sharp is paramount. This endpoint allows you to upgrade an installed 'muscle'—a specific skill module in your organization—to a newer version. It's like giving your organization's AI a new set of tools to tackle tasks more efficiently, ensuring you're always at the cutting edge of technology.

Request Body schema: application/json
required
version
required
string

The semantic version number to which the muscle should be upgraded.

force
boolean

Whether to force the upgrade even if the version is lower.

Responses

Request samples

Content type
application/json

This example shows a typical request to upgrade a muscle to version 2.1.0.

{
  • "version": "2.1.0",
  • "force": false
}

Response samples

Content type
application/json

An example response showing a successfully upgraded muscle.

{
  • "id": "muscle-12345",
  • "org_did": "did:human:acme-org",
  • "muscle_id": "muscle-alpha",
  • "version_installed": "2.1.0",
  • "asset_id": "asset-67890",
  • "config": { },
  • "installed_at": "2023-10-25T14:48:00.000Z",
  • "installed_by_did": "did:human:agent-jane",
  • "status": "active"
}

Muscle Management

Soft-delete an organization's muscle

This endpoint allows organizations to gracefully retire skills, known as 'muscles', by marking them as 'uninstalled'. This mechanism ensures a clean audit trail while preserving historical data, enabling organizations to maintain transparency and compliance.

Responses

Response samples

Content type
application/json

An example where the muscle is successfully uninstalled.

{
  • "status": "uninstalled",
  • "muscle_id": "muscle-abc123"
}

Upgrades

Upgrade an installed muscle version

In the dynamic world of AI-powered organizations, keeping your capabilities sharp is paramount. This endpoint allows you to upgrade an installed 'muscle'—a specific skill module in your organization—to a newer version. It's like giving your organization's AI a new set of tools to tackle tasks more efficiently, ensuring you're always at the cutting edge of technology.

Request Body schema: application/json
required
version
required
string

The semantic version number to which the muscle should be upgraded.

force
boolean

Whether to force the upgrade even if the version is lower.

Responses

Request samples

Content type
application/json

This example shows a typical request to upgrade a muscle to version 2.1.0.

{
  • "version": "2.1.0",
  • "force": false
}

Response samples

Content type
application/json

An example response showing a successfully upgraded muscle.

{
  • "id": "muscle-12345",
  • "org_did": "did:human:acme-org",
  • "muscle_id": "muscle-alpha",
  • "version_installed": "2.1.0",
  • "asset_id": "asset-67890",
  • "config": { },
  • "installed_at": "2023-10-25T14:48:00.000Z",
  • "installed_by_did": "did:human:agent-jane",
  • "status": "active"
}

Upgrade a connector to a new version

In the ever-evolving landscape of digital tools, keeping your connectors up-to-date is paramount for leveraging new features and maintaining security. This endpoint allows organizations to seamlessly upgrade their connectors to newer versions, ensuring they are always operating with the latest capabilities.

Request Body schema: application/json
required
version
required
string

The semantic version number to upgrade the connector to, e.g., '1.1.0'.

force
boolean

Flag to force the upgrade even if it is a downgrade.

Responses

Request samples

Content type
application/json

Example showing how to upgrade a connector to version 2.0.0

{
  • "version": "2.0.0",
  • "force": false
}

Response samples

Content type
application/json
{
  • "installation_id": "inst-12345",
  • "connector_id": "conn-67890",
  • "version_installed": "2.0.0"
}

Onboarding

Select and install a persona

Empower your organization by selecting a persona that aligns with your goals, ensuring the necessary agents are installed seamlessly. This endpoint orchestrates essential configurations, making your workspace ready for action.

Request Body schema: application/json
required
personaId
required
string

Unique identifier for the desired persona.

org_did
string

Decentralized identifier for the organization, required if not in token.

Responses

Request samples

Content type
application/json

Selecting a persona with organization context provided.

{
  • "personaId": "persona-123",
  • "org_did": "did:org:acme-inc"
}

Response samples

Content type
application/json

Persona selected and agents installed for Acme Corp.

{
  • "personaId": "persona-123",
  • "displayName": "Acme Persona",
  • "agentCount": 3,
  • "status": "installed",
  • "installations": [
    ],
  • "message": "Acme Persona: installed 3 required agents for your workspace."
}

Persona

Select and install a persona

Empower your organization by selecting a persona that aligns with your goals, ensuring the necessary agents are installed seamlessly. This endpoint orchestrates essential configurations, making your workspace ready for action.

Request Body schema: application/json
required
personaId
required
string

Unique identifier for the desired persona.

org_did
string

Decentralized identifier for the organization, required if not in token.

Responses

Request samples

Content type
application/json

Selecting a persona with organization context provided.

{
  • "personaId": "persona-123",
  • "org_did": "did:org:acme-inc"
}

Response samples

Content type
application/json

Persona selected and agents installed for Acme Corp.

{
  • "personaId": "persona-123",
  • "displayName": "Acme Persona",
  • "agentCount": 3,
  • "status": "installed",
  • "installations": [
    ],
  • "message": "Acme Persona: installed 3 required agents for your workspace."
}

Presence

Report device presence and status

Integrate seamlessly with HumanOS by reporting real-time device presence. This endpoint captures the essence of human-device interaction, enabling dynamic task routing and enhancing AI safety through accurate modality tracking.

Request Body schema: application/json
required
device_id
required
string

Unique identifier for the device

modality
string
Default: "text"
Enum: "text" "voice" "spatial" "compact"

The interaction modality, such as text or voice

accessories
Array of strings

List of accessories used with the device

bandwidth_tier
string

Current bandwidth tier of the device

Responses

Request samples

Content type
application/json

Reporting presence with a text modality

{
  • "device_id": "device123",
  • "modality": "text",
  • "accessories": [
    ],
  • "bandwidth_tier": "high"
}

Response samples

Content type
application/json
null

Device

Report device presence and status

Integrate seamlessly with HumanOS by reporting real-time device presence. This endpoint captures the essence of human-device interaction, enabling dynamic task routing and enhancing AI safety through accurate modality tracking.

Request Body schema: application/json
required
device_id
required
string

Unique identifier for the device

modality
string
Default: "text"
Enum: "text" "voice" "spatial" "compact"

The interaction modality, such as text or voice

accessories
Array of strings

List of accessories used with the device

bandwidth_tier
string

Current bandwidth tier of the device

Responses

Request samples

Content type
application/json

Reporting presence with a text modality

{
  • "device_id": "device123",
  • "modality": "text",
  • "accessories": [
    ],
  • "bandwidth_tier": "high"
}

Response samples

Content type
application/json
null

Policy Management

Create or Update Organization Policy

Orchestrate your organization's operations with precision by defining or updating policies. This endpoint enables organizations to enforce rules that govern their conduct within the HUMAN network, ensuring alignment with strategic goals and regulatory requirements.

Request Body schema: application/json
required
policy_type
required
string
Enum: "marketplace" "agent_autonomy_domain" "audit_retention" "data_residency" "transparency_redaction"

The type of policy to apply.

policy_rules
required
object

The rules defining the policy. Specific structure depends on the policy_type.

Responses

Request samples

Content type
application/json

An example of creating a marketplace policy.

{
  • "policy_type": "marketplace",
  • "policy_rules": {
    }
}

Response samples

Content type
application/json
null

Apply a Policy Pack to Marketplace

This endpoint allows you to apply a specified policy pack to a marketplace, ensuring the seamless integration of compliance and security measures. By orchestrating policy applications, HUMAN facilitates a streamlined approach to managing marketplace operations with confidence.

Request Body schema: application/json
required
dry_run
boolean

If true, the policy pack will not actually be applied, allowing you to preview any changes.

Responses

Request samples

Content type
application/json

Demonstrating a dry run to preview policy effects without applying them.

{
  • "dry_run": true
}

Response samples

Content type
application/json

The policy pack was applied to the marketplace with ID pid-12345.

{
  • "applied": true,
  • "pack_id": "pid-12345"
}

Retrieve structured policy summaries

Discover the governance of your organization through HUMAN's curated policy summaries. This endpoint allows organizations to gain insights into their policy landscape by fetching structured overviews, helping you navigate and enhance your task orchestration with AI safety.

Responses

Response samples

Content type
application/json

Acme Corp retrieves policy summaries to ensure compliance and operational efficiency.

{
  • "data": [
    ],
  • "limit": 20,
  • "cursorField": "policy_id",
  • "hasMore": false
}

Delete a structured policy by ID

In the intricate dance of task automation, sometimes a policy outlives its usefulness. This endpoint allows organizations to gracefully retire a structured policy, ensuring that their orchestration remains agile and adaptive. By removing outdated policies, organizations can streamline their operations and maintain a clean, efficient task routing system.

Responses

Response samples

Content type
application/json
null

Fetch structured policy details by ID

Retrieve intricate policy details tailored to your organization's dynamics. This endpoint empowers organizations to understand and manage their task routing policies effectively, ensuring alignment with their AI safety protocols.

Responses

Response samples

Content type
application/json

Represents a policy for handling invoices within the 'acme' organization.

{
  • "policy_id": "a123b456-c789-0123-d456-789e012f3456",
  • "name": "Invoice Processing",
  • "policy": {
    },
  • "active": true,
  • "version": 2,
  • "team_id": "f7890123-4567-89ab-cdef-0123456789ab",
  • "agent_did": "did:human:agents:acme-processor",
  • "created_at": "2023-01-15T08:00:00Z",
  • "updated_at": "2023-09-20T14:30:00Z"
}

Update structured HumanOS policy

This endpoint empowers organizations to update their structured policies within the HumanOS task routing system. By maintaining accurate and current policy definitions, organizations can ensure AI safety and compliance. This operation is crucial for organizations like 'acme' who need to adapt their policy frameworks promptly.

Request Body schema: application/json
required
name
string

A descriptive name for the policy.

object

The new policy document to validate and apply.

active
boolean

Indicates whether the policy should be active.

Responses

Request samples

Content type
application/json

An example of updating a policy with a new name and active status.

{
  • "name": "Updated Invoice Processing Policy",
  • "policy": {
    },
  • "active": true
}

Response samples

Content type
application/json
{
  • "policy_id": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "Updated Invoice Processing Policy",
  • "active": true,
  • "version": 2,
  • "updated_at": "2023-10-01T12:34:56Z"
}

Update or create organizational policy

This endpoint empowers administrators to seamlessly update or create policies for their organization, ensuring that the latest configurations are always in place. By leveraging a cryptographic identity (Passport), the HUMAN protocol guarantees that only authorized users can manage these critical settings.

Request Body schema: application/json
required
policy_json
required
object

The JSON object representing the organization's policy settings. It acts as a partial overlay to merge with existing policies.

Responses

Request samples

Content type
application/json

This example demonstrates updating the policy document for Acme Corporation, adding a new billing rule.

{
  • "policy_json": {
    }
}

Response samples

Content type
application/json
{
  • "org_did": "did:human:acmeCorp123",
  • "merged_policy": {
    },
  • "updated_at": "2023-10-23T14:55:00Z"
}

Update Team Policy Overlay

Seamlessly merge new AI safety policies into your team's existing configuration, ensuring that your organization's human-AI orchestration remains both agile and robust. This endpoint empowers administrators by allowing them to update team-specific capabilities, harnessing the strength of distributed ledger technology for impeccable provenance tracking.

Request Body schema: application/json
required
policy_json
required
object

A JSON object representing the policy overlay to merge into the existing team policy.

Responses

Request samples

Content type
application/json

An example showing how to update the invoicing policy for a team within an organization.

{
  • "policy_json": {
    }
}

Response samples

Content type
application/json
{
  • "org_did": "did:example:acme",
  • "team_id": "team-1234",
  • "merged_policy": {
    },
  • "updated_at": "2023-12-01T12:34:56Z"
}

Update User's Policy Overlay

Empower users to tailor their HumanOS task orchestration by updating their policy overlays. This endpoint allows a delegation to redefine how tasks are routed, ensuring that the AI respects personalized rules and preferences.

Request Body schema: application/json
required
policy_json
required
object

A partial user policy overlay defining task routing rules.

Responses

Request samples

Content type
application/json

An example showing how to update task routing preferences to prioritize safety checks.

{
  • "policy_json": {
    }
}

Response samples

Content type
application/json
{
  • "org_did": "did:example:123456789abcdefghi",
  • "passport_did": "did:example:abcdef123456789",
  • "merged_policy": {
    },
  • "updated_at": "2023-10-15T12:30:00Z"
}

Update User Policy with Passport DID

Enhance user experience by updating policy overlays for users identified by their Passport DID. This endpoint empowers administrators to tailor AI safety and task routing policies, ensuring the HUMAN platform aligns with organizational needs.

Request Body schema: application/json
required
policy_json
required
object

A JSON object that represents the user's policy settings.

Responses

Request samples

Content type
application/json

Example of a policy update for user tasks and AI interaction.

{
  • "policy_json": {
    }
}

Response samples

Content type
application/json
{
  • "org_did": "org:example-corp",
  • "passport_did": "did:human:123456789abcdefghi",
  • "merged_policy": {
    },
  • "updated_at": "2023-10-15T12:34:56Z"
}

Policies

Retrieve organization policies list

Dive into the strategic framework of an organization by retrieving its policies. This endpoint allows you to access the structured set of rules and guidelines that govern an organization identified by its DID. It's a window into understanding how the organization orchestrates its operations.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Compute

Configure Organization Compute Policy

Empower your organization by setting a compute policy that aligns with your operational needs, either opting for self-hosted resources or leveraging HUMAN's infrastructure. This decision impacts cost management and resource allocation, ensuring flexibility and control over computational expenses.

Request Body schema: application/json
required
compute_mode
string
Enum: "BYOK" "HUMAN_HOSTED"
object

Responses

Request samples

Content type
application/json

An organization opting for HUMAN-hosted compute with specified spend limits.

{
  • "compute_mode": "HUMAN_HOSTED",
  • "compute_policy": {
    }
}

Response samples

Content type
application/json
null

Retrieve monthly compute usage by organization

Unveil your organization's compute usage story for the current month. This endpoint empowers cloud administrators to monitor resource consumption and manage billing efficiently, ensuring that usage aligns with organizational plans and authorized top-ups. Understand your usage patterns and avoid surprises by staying informed.

Responses

Response samples

Content type
application/json
{
  • "orgs": [
    ]
}

Devices

Retrieve paginated list of devices

Explore the vast network of devices under your organization's purview. This endpoint allows you to seamlessly paginate through enrolled devices, ensuring you stay on top of your technological landscape. Whether tracking IoT devices or managing enterprise hardware, maintain a clear view of your assets.

Responses

Response samples

Content type
application/json

A list of devices for the organization ACME Corp.

{
  • "data": [
    ],
  • "hasMore": false,
  • "limit": 2,
  • "nextCursor": "opaqueCursor123"
}

Initiate a device sync session for a Passport

Embarking on a new journey with your Passport's devices, this endpoint initiates a synchronization process. It ensures that only authorized devices can partake in this dance of data, safeguarding your cryptographic identity with precision and trust.

Request Body schema: application/json
required
initiating_device_id
required
string

The ID of the device initiating the sync.

current_device_signature
required
string

The JWS signature from the current device.

ephemeral_public_key
required
string

Ephemeral public key for secure communication.

p2p_capable
boolean

Flag indicating if the session supports peer-to-peer mode.

Responses

Request samples

Content type
application/json

Initiating a sync session with essential details and optional P2P capability.

{
  • "initiating_device_id": "device123",
  • "current_device_signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "ephemeral_public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQ...",
  • "p2p_capable": true
}

Response samples

Content type
application/json
{
  • "session_id": "sess-abc123",
  • "qr_payload": {
    },
  • "expires_at": "2023-11-15T15:00:00Z",
  • "p2p_mode": true,
  • "signal_url": "/v1/passports/did%3Ahuman%3A1234/devices/sync/sess-abc123/signal"
}

Signal device sync for passport session

This endpoint is a digital bridge connecting devices within a user's cryptographic identity, enabling them to exchange signaling information securely. By allowing devices to sync signals like 'offer', 'answer', or 'ice-candidate', it ensures seamless interaction and coordination within the HUMAN network, enhancing efficiency and safety.

Request Body schema: application/json
required
type
required
string
Enum: "offer" "answer" "ice-candidate"

The type of signal being sent

payload
required
string

The signaling payload data to be transmitted

from_device_id
required
string

Identifier of the device sending the signal

Responses

Request samples

Content type
application/json

A device sends an offer to initiate a WebRTC connection

{
  • "type": "offer",
  • "payload": "v=0\r\n...",
  • "from_device_id": "device-123"
}

Response samples

Content type
application/json

Devices successfully exchanged signaling information

{
  • "signals": [
    ]
}

Retrieve synchronized signals for device

Harness the potential of secure identity with HUMAN's Passport by retrieving synchronized signals for a specific device session. This endpoint empowers users to poll device signals, ensuring that only authorized individuals can access their cryptographic identities' data.

Responses

Response samples

Content type
application/json

An example showing successfully fetched signals for a session.

{
  • "signals": [
    ]
}

Topology

Retrieve organizational device topology

Dive into the intricate web of devices and their interconnections within an organization. This endpoint unveils the topology graph, a vivid map that helps administrators visualize and manage their digital ecosystem efficiently.

Responses

Response samples

Content type
application/json

Visual representation of Acme's interconnected devices.

{
  • "nodes": [
    ],
  • "edges": [
    ]
}

Network Configuration

Create and manage device connections

Unleash the potential of interconnected devices by forging new pathways between them. This endpoint allows organizations to establish logical edges between devices, weaving a network where data flows seamlessly and securely. By connecting devices, organizations can optimize operations and enhance collaboration.

Request Body schema: application/json
required
org_did
required
string

Decentralized Identifier for the organization

source_device_id
required
string

Identifier of the source device

target_device_id
required
string

Identifier of the target device

edge_type
string
Default: "data"

Type of edge connecting devices

metadata
object

Additional information about the edge

Responses

Request samples

Content type
application/json

This example establishes a data connection between two devices within the Acme organization.

{
  • "org_did": "did:haio:acme",
  • "source_device_id": "device-123",
  • "target_device_id": "device-456",
  • "edge_type": "data",
  • "metadata": {
    }
}

Response samples

Content type
application/json
null

Health Monitoring

Update health status of a device

In the intricate dance of human and AI collaboration, devices play a pivotal role. This endpoint allows devices to signal their current health status, ensuring timely intervention and seamless operations. By keeping the HUMAN ecosystem informed, we maintain the harmony essential for efficient orchestration.

Request Body schema: application/json
required
health_status
required
string
Enum: "healthy" "degraded" "error" "unknown" "offline"

The current health status of the device.

Responses

Request samples

Content type
application/json

A device signaling it's in a healthy state.

{
  • "health_status": "healthy"
}

Response samples

Content type
application/json
null

Audit

Retrieve audit events for an organization

Navigate through the intricate web of decision-making within your organization with this endpoint, offering a flat timeline of governed decision events. Designed for transparency and accountability, it empowers users to audit actions and decisions made under the auspices of human-AI collaboration.

Responses

Response samples

Content type
application/json

Audit log of Acme Corp showing recent decision events

{
  • "data": [
    ],
  • "limit": 50,
  • "hasMore": false,
  • "nextCursor": null
}

Retrieve execution provenance graph

Dive into the intricate web of task execution with our provenance graph. By querying this endpoint, you uncover the nodes and edges that outline the path your execution traversed. This transparency is not just for oversight but also for insights, enabling you to optimize workflows and trace the lineage of your data processes.

Responses

Response samples

Content type
application/json

Shows the provenance graph for an invoice processing execution at Acme Org.

{
  • "execution_id": "123e4567-e89b-12d3-a456-426614174000",
  • "nodes": [
    ],
  • "edges": [
    ]
}

Retrieve AI-generated audit summaries

Dive into the AI's lens on your organization with this endpoint. It delivers curated summaries generated by our Audit Summarizer Agent, helping you understand the intricate details of your organizational activities. This service empowers users by providing insights that can guide strategic decision-making.

Responses

Response samples

Content type
application/json

An example response where the organization 'acme' reviews its recent audit summaries.

{
  • "data": [
    ]
}

Retrieve retention policies for organization

Discover the retention periods your organization has set for its data tiers. By understanding these configurations, you can better align your data management strategies with organizational policies and compliance requirements.

Responses

Response samples

Content type
application/json

An organization with hot tier retention only.

{
  • "org_did": "did:haio:acme",
  • "retention_days_hot": 30,
  • "retention_days_warm": null,
  • "retention_days_cold": null,
  • "tiers_implemented": [
    ]
}

Retrieve Pre-built Audit Report Catalog

Unveil the hidden narratives behind your operations with HUMAN's pre-built audit report catalog. This endpoint grants you a gateway to a curated collection of insightful reports, each designed to shed light on the orchestration of human and AI activities across your organization. Discover patterns, enhance transparency, and drive informed decisions.

Responses

Response samples

Content type
application/json

A glimpse into the diverse range of audit reports available.

{
  • "data": [
    ]
}

Retrieve detailed audit report data

Delve into the intricate details of your organization's decision-making footprint. This endpoint executes a selected pre-built audit report, providing insights on delegation, trust changes, autonomy ratios, and connector usage. Use this tool to ensure transparency and governance in your human-AI interactions.

Responses

Response samples

Content type
application/json

Example of a delegation usage report for acme org.

{
  • "report_id": "delegation-usage",
  • "generated_at": "2023-10-01T12:00:00Z",
  • "period_days": 30,
  • "org_did": "did:example:acme",
  • "row_count": 150,
  • "data": [
    ]
}

Export audit events in various formats

Dive into the rich history of your organization's decisions with the ability to export audit events in CSV or JSON format. This endpoint empowers compliance and oversight by offering a comprehensive view of critical actions taken within your organization. Understand the provenance of your decisions and ensure accountability at every step.

Responses

Response samples

Content type
application/json

A JSON response containing a list of audit events.

{
  • "data": [
    ],
  • "count": 1,
  • "exported_at": "2023-09-10T15:00:00Z"
}

Audit missing billing categories

This endpoint performs a crucial audit on cloud metering events to ensure that all entries have a specified billing category. It's essential for maintaining accurate billing and reporting, helping organizations like 'Acme Corp' avoid financial discrepancies.

Responses

Response samples

Content type
application/json

Example response showing a scenario where some events are missing billing categories.

{
  • "untagged_count": 5,
  • "checked_at": "2023-10-05T14:48:00Z"
}

Retrieve Passport Consent Events

Explore the consent history of a cryptographic identity with precision and insight. This endpoint unveils the trail of consent events linked to a passport, showcasing how various resources have been accessed and utilized with explicit permissions. It empowers users to audit and understand the access patterns associated with their digital identity.

Responses

Response samples

Content type
application/json

Retrieve a paginated list of consent events for a digital passport.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Retrieve audit events from HumanOS

Unveil the intricate dance of actions within your organization by exploring the audit trail maintained by HumanOS. This endpoint allows you to sift through the past, examining the orchestration of tasks and decisions made by both humans and AI. Whether you're tracking down anomalies or ensuring compliance, these records hold the key.

Responses

Response samples

Content type
application/json

Retrieve the latest audit events for monitoring task execution

{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "eyJfaHVtYW5vc19hdWRpdF9zb3J0IjoiY3JlYXRlZF9hdCIsImlkIjoxMDAwMX0="
}

Calibrate audit event risk embeddings

Enhance your audit insights by recalibrating the risk scores of humanos audit events with fresh embeddings. This endpoint exists to ensure your risk assessment remains accurate and up-to-date, leveraging the power of AI for more precise decision-making.

Request Body schema: application/json
required
mode
string
Enum: "full" "incremental"

Determines whether to perform a full recalibration or an incremental update.

limit
integer [ 1 .. 500 ]
Default: 100

Limits the number of events processed in this request.

after_id
integer

The ID to start processing from, for pagination purposes.

Responses

Request samples

Content type
application/json

Requests a full recalibration of audit events with a limit of 200.

{
  • "mode": "full",
  • "limit": 200
}

Response samples

Content type
application/json
null

Retrieve decision audit chain details

Explore the intricate web of decisions with this endpoint, which unveils the comprehensive audit trail of a specific decision. By fetching the materialized decision chain, organizations can ensure accountability and transparency in their decision-making processes, paving the way for improved governance and trust.

Responses

Response samples

Content type
application/json
{
  • "decision": {
    },
  • "events": [
    ]
}

Retrieve structured decision explanation

Unlock the story behind a decision with detailed provenance and routing signals. This endpoint offers a deep dive into the decision-making process, providing insights into the integrity and policy conformance of AI-augmented human actions.

Responses

Response samples

Content type
application/json

An example showing decision explanation for an AI decision.

{
  • "decision_id": "dec123",
  • "summary": "AI decision for invoice processing",
  • "policy_version_snapshot": "v2023.10",
  • "escalation_occurred": false,
  • "override_occurred": true,
  • "integrity_status": "verified",
  • "routing_signals": [
    ],
  • "citations": [
    ]
}

Retrieve audit decisions within an organization

Dive into the decision-making process of your organization with the power of audit insights. Understanding who decided what and why is crucial for transparent operations and compliance. This endpoint equips organizations with the ability to pull detailed decision records, ensuring accountability and traceability.

Responses

Response samples

Content type
application/json

Retrieve decisions for the 'acme' organization, focusing on a specific workflow within a date range.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "updated_at",
  • "hasMore": false,
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Retrieve Audit Decision Chain Details

Uncover the provenance of decisions by exploring their audit trail within the HUMAN ecosystem. This endpoint serves as a gateway to transparency, allowing organizations to verify the integrity and source of decisions made by their systems.

Responses

Response samples

Content type
application/json

An organization retrieves the chain details of a decision to audit its origin and verify its integrity.

{
  • "decision_id": "123e4567-e89b-12d3-a456-426614174000",
  • "provenance_chain_id": "chain-abc123",
  • "source_event_hashes": [
    ],
  • "chain_integrity": "b1946ac92492d2347c6235b4d2611184"
}

Retrieve and explain an audit decision

Unravel the intricacies of a specific audit decision by fetching its detailed explanation. This endpoint empowers organizations to understand the outcomes of their decision-making processes, ensuring transparency and accountability in the orchestration of human and AI interactions.

Responses

Response samples

Content type
application/json

An example response for a successful audit decision explanation retrieval.

{
  • "decision_id": "12345",
  • "summary": "Approved invoice processing",
  • "policy_version_snapshot": "v2023.10.01",
  • "escalation_occurred": false,
  • "override_occurred": true,
  • "integrity_status": "verified",
  • "evidence_status": "complete"
}

Retrieve audit override events history

Dive into the past and explore audit override events for your organization. This endpoint offers a window into the decisions that altered the usual course of operations, enabling transparency and accountability. Use it to track changes, understand discrepancies, and ensure compliance with established protocols.

Responses

Response samples

Content type
application/json

Shows a paginated list of past override events for the organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "occurred_at",
  • "hasMore": true,
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Identify Missing Audit Attestations

In the vast landscape of audit trails, some stones are left unturned. This endpoint shines a light on the gaps in your audit attestations, ensuring every decision is verified. By identifying where attestations are missing, organizations can maintain integrity and trust in their processes.

Responses

Response samples

Content type
application/json

An example response where certain attestations are missing.

{
  • "data": [
    ],
  • "scanned_decisions": 150,
  • "missing_count": 2
}

Create and store audit evidence bundles

This endpoint is a crucial part of maintaining transparency and trust within the HUMAN ecosystem. It enables organizations to submit decision-making evidence, ensuring accountability and providing a clear audit trail. By storing these bundles, it supports robust AI governance and compliance efforts.

Request Body schema: application/json
required
decision_ids
required
Array of strings

List of decision IDs related to the evidence bundle.

format
string

Format in which the evidence bundle should be stored, defaults to 'ops'.

generated_by
string

Identifier for the entity generating the evidence, defaults to the agent audit API if not provided.

Responses

Request samples

Content type
application/json

A typical example where an organization submits an evidence bundle for multiple decisions.

{
  • "decision_ids": [
    ],
  • "format": "json",
  • "generated_by": "acmeCorpAuditTool"
}

Response samples

Content type
application/json
{
  • "bundle_id": "bundle-98765",
  • "status": "created"
}

Compare Two Audit Decision Chains

Dive deep into decision-making by comparing two audit decision chains. Unveil the differences in policies, workflows, and overrides to ensure your organization’s audits are transparent and accountable.

Request Body schema: application/json
required
decision_id_a
required
string

Unique identifier for the first decision

decision_id_b
required
string

Unique identifier for the second decision

Responses

Request samples

Content type
application/json

Compares two decisions to identify changes in policy versions and overrides.

{
  • "decision_id_a": "dec123",
  • "decision_id_b": "dec456"
}

Response samples

Content type
application/json
{
  • "a": {
    },
  • "b": {
    },
  • "diff": {
    }
}

Subscribe to audit event notifications

In the pursuit of seamless orchestration, this endpoint was envisioned to allow subscribers to receive notifications of audit events. However, this feature is currently unimplemented. For now, it serves as a gentle reminder to use the POST /v1/webhooks/subscriptions endpoint, where audit event types can be specified for notifications. Stay tuned as the HUMAN platform evolves to support more intricate functionalities.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve decision audit by ID

Dive into the depths of decision-making with the HUMAN platform's decision audit retrieval. This endpoint lets you explore the intricate web of decisions made within your organization, ensuring transparency and traceability in a world increasingly driven by AI and human collaboration. Whether you are validating an audit grant or simply accessing your own decision history, this endpoint guarantees that every decision is accounted for.

Responses

Response samples

Content type
application/json

A comprehensive audit of a decision within the 'acme' organization, showcasing the decision's origins and lifecycle.

{
  • "id": "dec-12345",
  • "title": "Approve Invoice Payment",
  • "workflow_id": "wf-67890",
  • "org_did": "did:human:acme",
  • "decision_type": "Approval",
  • "status": "Completed",
  • "risk_level": "Low",
  • "policy_checks": [
    ],
  • "escalation_occurred": false,
  • "override_occurred": false,
  • "provenance_chain_id": "chain-12345",
  • "actors": [
    ],
  • "graph_execution_id": "exec-54321",
  • "created_at": "2023-10-01T10:00:00Z",
  • "updated_at": "2023-10-02T12:00:00Z",
  • "escalation_events": [ ],
  • "override_events": [ ],
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Assemble audit decisions for an organization

This endpoint meticulously assembles audit decisions, weaving together a tapestry of organizational insights. It ensures every decision is documented with precision, offering a transparent view of actions taken within the HUMAN platform. This orchestration is essential for maintaining accountability and trust in automated processes.

Responses

Response samples

Content type
application/json

A successful response indicating the number of decisions assembled and the timestamp.

{
  • "upserted": 42,
  • "assembled_at": "2023-10-15T10:00:00Z"
}

Challenge an audit decision

In the dynamic world of AI governance, sometimes decisions need a second look. This endpoint allows organizations to challenge audit decisions, ensuring transparency and accuracy. By leveraging HUMAN's capability graph, users can request further review or clarification, fostering trust in AI interactions.

Request Body schema: application/json
required
challenger_passport_id
string

The Passport ID of the challenger.

reason
string

The reason for the challenge.

narrative
string

Additional narrative or context for the challenge.

requested_action
string

The action the challenger is requesting, such as 'second_review'.

Responses

Request samples

Content type
application/json

An organization requests a second review of an audit decision due to perceived discrepancies.

{
  • "challenger_passport_id": "passport:12345",
  • "reason": "Discrepancy in data interpretation",
  • "narrative": "The decision was based on outdated data.",
  • "requested_action": "second_review"
}

Response samples

Content type
application/json
{
  • "challenge_id": "chal_67890",
  • "provenance_chain_id": "chal_chain_chal_67890",
  • "status": "open"
}

Fetch audit challenges for organization

Retrieve a list of audit challenges associated with your organization, enabling you to track and manage compliance and decision-making processes. This endpoint is vital for organizations like 'acme' to ensure transparency and accountability in their AI task orchestration.

Responses

Response samples

Content type
application/json

A realistic example where 'acme' organization fetches audit challenges with pagination.

{
  • "data": [
    ],
  • "limit": 2,
  • "cursorField": "createdAt",
  • "hasMore": true,
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Retrieve a specific audit challenge case

Uncover the story behind a specific challenge in your organization's audit trail. Every challenge tells a tale of compliance and decision-making, ensuring transparency and accountability within the HUMAN ecosystem.

Responses

Response samples

Content type
application/json

Retrieving an audit challenge case for organization with DID 'did:human:acme'.

{
  • "id": "challenge-123",
  • "decision_id": "decision-456",
  • "org_did": "did:human:acme",
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Update audit challenge status and disposition

In the complex dance of ensuring compliance, this endpoint allows organizations to update the status and disposition of audit challenges. By empowering organizations to mark challenges as resolved or withdrawn, it orchestrates a seamless interaction between human oversight and AI precision, ensuring that the audit trail remains robust and transparent.

Request Body schema: application/json
required
status
required
string
Enum: "resolved" "withdrawn" "under_review"

The new status of the challenge.

disposition
string

A note or decision regarding the challenge.

Responses

Request samples

Content type
application/json

An example showing the resolution of a challenge.

{
  • "status": "resolved",
  • "disposition": "The issue was addressed satisfactorily."
}

Response samples

Content type
application/json
{
  • "challenge_id": "12345",
  • "updated": true
}

Retrieve Active Audit Grants

Discover the active grants for an organization, granting you insights into what capabilities are being utilized and by whom. This endpoint helps maintain transparency and accountability within the HUMAN network, ensuring all actions are traceable and verifiable.

Responses

Response samples

Content type
application/json

A list of active audit grants for organization 'acme'.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at",
  • "hasMore": false,
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Create a new audit grant

In the HUMAN platform, oversight and transparency are paramount. This endpoint empowers organizations to delegate audit rights through cryptographic Passports, ensuring that the right individuals can review and validate transactions. By facilitating controlled access, it maintains trust and security within the system.

Request Body schema: application/json
required
grantee_passport_id
required
string

The Passport ID of the grantee who receives the audit rights.

granter_passport_id
string

The Passport ID of the granter delegating the audit rights.

purpose
string

The reason for granting the audit rights, e.g., 'audit_review'.

mode
string

The mode of audit rights, e.g., 'delegated_investigation'.

object

The scope of the audit rights, defined as a JSON object.

expires_at
string <date-time>

The expiration date and time for the audit grant.

Responses

Request samples

Content type
application/json

Delegating audit rights to an external auditor for compliance checks.

{
  • "grantee_passport_id": "passport:12345",
  • "granter_passport_id": "passport:67890",
  • "purpose": "compliance_audit",
  • "mode": "delegated_investigation",
  • "scope": {
    },
  • "expires_at": "2023-12-31T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "grant_id": "agrant:1234567890"
}

Retrieve audit views for an organization

Explore the intricate records of saved audit views within an organization on the HUMAN platform. This endpoint helps administrators track and manage the audit trail of various views, ensuring transparency and accountability in data handling practices.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at",
  • "hasMore": false
}

Create a new audit view

In a world where transparency is paramount, creating personalized audit views empowers organizations to tailor how they monitor their operations. This endpoint allows you to define and save custom views, enriching your insight into the complex dance of human and AI interactions.

Request Body schema: application/json
required
name
required
string

The name of the audit view.

owner_passport_id
required
string

Passport ID of the owner creating this view.

object

Custom configuration for filtering the audit data.

Responses

Request samples

Content type
application/json

An example where the 'acme' organization creates a view to track invoice processing audits.

{
  • "name": "Invoice Processing",
  • "owner_passport_id": "passport:acme:12345",
  • "filter_config": {
    }
}

Response samples

Content type
application/json
{
  • "view_id": "aview:001122334455"
}

Create a new evidence bundle

Embark on a journey to safeguard truth with this endpoint, which crafts cryptographic evidence bundles from decision data. Harness the power of provenance tracking to ensure every decision within an organization is both transparent and verifiable.

Request Body schema: application/json
required
decision_ids
required
Array of strings

List of decision IDs to include in the bundle.

format
string

The format of the evidence bundle, defaulting to 'ops'.

generated_by
string

The DID of the entity generating the bundle. Defaults to the organization DID if not provided.

Responses

Request samples

Content type
application/json

An example of creating an evidence bundle with specified decision IDs.

{
  • "decision_ids": [
    ],
  • "format": "ops",
  • "generated_by": "did:example:generator"
}

Response samples

Content type
application/json
null

Create a recurring Workbench investigation template

In the intricate dance of human and AI collaboration, maintaining oversight is crucial. This endpoint allows you to save configurations for recurring investigations within the Workbench, ensuring consistent monitoring and analysis. By setting entry points and filters, you can automate the oversight process, harnessing the power of data to drive informed decisions.

Request Body schema: application/json
required
name
required
string

A unique name for the investigation template.

owner_passport_id
required
string

The Passport ID of the template owner.

entry_point_type
required
string

The type of entry point for the investigation.

object

A JSON object detailing filter configurations.

investigation_mode
string

The mode of investigation, defaults to 'ops'.

Responses

Request samples

Content type
application/json

A typical configuration for a compliance audit.

{
  • "name": "Compliance Audit Q1",
  • "owner_passport_id": "passport:12345",
  • "entry_point_type": "financial",
  • "filter_config": {
    },
  • "investigation_mode": "ops"
}

Response samples

Content type
application/json
{
  • "template_id": "wbtpl-1234567890"
}

Retrieve audit templates for user

Uncover a treasure trove of audit workbench templates tailored for a specific user within an organization. This endpoint empowers organizations to seamlessly track and manage their audit templates, ensuring efficiency and compliance through precise task orchestration.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "createdAt",
  • "hasMore": true
}

Retrieve audit decision details by ID

Dive into the history of an organization's decision-making process by fetching detailed records of audit decisions. This endpoint reveals the intricacies of decision provenance, ensuring transparency and accountability in AI-assisted operations.

Responses

Response samples

Content type
application/json

Shows a complete audit decision for organization 'acme'.

{
  • "id": "dec123",
  • "title": "Invoice Review",
  • "workflow_id": "wf456",
  • "org_did": "did:human:acme",
  • "decision_type": "approval",
  • "status": "completed",
  • "risk_level": "low",
  • "policy_checks": [ ],
  • "escalation_occurred": false,
  • "override_occurred": false,
  • "provenance_chain_id": "chain789",
  • "actors": [ ],
  • "graph_execution_id": "exec101",
  • "policy_version_snapshot": "v1.0",
  • "integrity_status": "verified",
  • "created_at": "2023-10-02T14:48:00Z",
  • "updated_at": "2023-10-02T15:00:00Z"
}

Retrieve audit decisions with flexible filtering

Explore the audit decisions made within your organization, leveraging powerful filters to navigate complex data. This endpoint is your window into the decision-making process, enabling transparency and compliance by surfacing the 'who,' 'what,' and 'why' behind each decision. By understanding these decisions, organizations can better orchestrate their human and AI resources, ensuring decisions align with their strategic goals.

Responses

Response samples

Content type
application/json

Acme Corp requests to view recent audit decisions, filtered by risk level and status.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursor": "2023-10-02T12:00:00Z",
  • "hasMore": false,
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Revoke an Audit Grant by ID

In the realm of audit management, control is paramount. This endpoint allows administrators to revoke an existing audit grant, ensuring that outdated or erroneous permissions are swiftly nullified. By invoking this, you secure the integrity of your audit processes when certain grants are no longer valid or necessary.

Responses

Response samples

Content type
application/json

This example shows a grant that was already revoked.

{
  • "grant_id": "123abc",
  • "revoked": false,
  • "already_revoked": true,
  • "revoked_at": "2023-01-15T08:30:00Z"
}

Retrieve organization's audit access log

Explore the intricate dance of responsibility and transparency with our audit access log, where organizational oversight meets accountability. This endpoint empowers audit administrators to meticulously track who accessed what and when, ensuring that every digital interaction is recorded for posterity.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "accessed_at",
  • "hasMore": false
}

Retrieve intent lineage details for analysis

Uncover the historical context and evolution of a specific intent within the HUMAN platform. This endpoint provides a comprehensive lineage, detailing its versions, associated resolution plans, and related artifacts. This insight is crucial for organizations aiming to audit or enhance their Human-AI orchestration strategies.

Responses

Response samples

Content type
application/json

Fetching the lineage for an intent used in Acme Corp's invoice processing.

{
  • "intent_brief": {
    },
  • "versions": [
    ],
  • "resolution_plan": {
    },
  • "scaffolded_artifacts": [
    ],
  • "execution_runs": [ ],
  • "approvals": [ ],
  • "audit_event_ids": [
    ]
}

Retrieve audit trail for Intent

Explore the history of an Intent, capturing its evolutionary journey through different versions and compilations. This endpoint provides a detailed audit trail, showcasing how an Intent has been shaped and compiled over time, ensuring transparency and traceability in decision-making.

Responses

Response samples

Content type
application/json
{
  • "intent_brief_id": "123e4567-e89b-12d3-a456-426614174000",
  • "versions": [
    ],
  • "compilations": [
    ],
  • "provenance_capabilities": [
    ],
  • "query_provenance": {
    }
}

Retrieve evidence audit by routing decision

Dive into the past decisions of our AI orchestrated tasks with this endpoint. By querying the audit trail of routing decisions, you gain insights into task assignments, ensuring transparency and accountability in AI-human collaborations.

Responses

Response samples

Content type
application/json

An audit record showing how a task was routed for the given decision ID.

{
  • "evidence": {
    }
}

Governance

Retrieve audit events for an organization

Navigate through the intricate web of decision-making within your organization with this endpoint, offering a flat timeline of governed decision events. Designed for transparency and accountability, it empowers users to audit actions and decisions made under the auspices of human-AI collaboration.

Responses

Response samples

Content type
application/json

Audit log of Acme Corp showing recent decision events

{
  • "data": [
    ],
  • "limit": 50,
  • "hasMore": false,
  • "nextCursor": null
}

Retrieve detailed audit report data

Delve into the intricate details of your organization's decision-making footprint. This endpoint executes a selected pre-built audit report, providing insights on delegation, trust changes, autonomy ratios, and connector usage. Use this tool to ensure transparency and governance in your human-AI interactions.

Responses

Response samples

Content type
application/json

Example of a delegation usage report for acme org.

{
  • "report_id": "delegation-usage",
  • "generated_at": "2023-10-01T12:00:00Z",
  • "period_days": 30,
  • "org_did": "did:example:acme",
  • "row_count": 150,
  • "data": [
    ]
}

Change founders synchronously with signatures

Join forces in a ceremonial moment to alter the fabric of your organization's leadership. This endpoint allows for immediate founder adjustments when all necessary signatures are provided, ensuring trust and authenticity in high-stakes decisions.

Request Body schema: application/json
required
action
required
string
Enum: "add" "remove"

Action to perform: 'add' to include a new founder, 'remove' to exclude an existing one.

founder_did
required
string^did:human:.*$

DID of the founder to be added or removed.

requested_by
required
string^did:human:.*$

DID of the founder proposing the change.

required
Array of objects

Array of signatures from current founders verifying the change.

Responses

Request samples

Content type
application/json

Example of adding a new founder to the organization with all required signatures.

{
  • "action": "add",
  • "founder_did": "did:human:12345",
  • "requested_by": "did:human:67890",
  • "signatures": [
    ]
}

Response samples

Content type
application/json
{
  • "org_did": "did:human:org:abcdef",
  • "action": "add",
  • "founder": {
    },
  • "founder_count": 4,
  • "threshold_required": 3,
  • "verified_approvers": [
    ],
  • "provenance_id": "prov_123456789"
}

Upgrade organization governance tier

Empower your organization to unlock new capabilities by upgrading its governance tier. This endpoint validates your organization’s readiness and executes a tier upgrade, ensuring compliance and integrity through rigorous checks. Elevate your organization's potential while maintaining transparency and security.

Request Body schema: application/json
required
One of
requested_by
required
string

DID of the founder requesting the upgrade

target_tier
required
integer
Enum: 1 2 3

The desired governance tier

Responses

Request samples

Content type
application/json

Upgrade an organization to Tier 2 with valid founder DID

{
  • "requested_by": "did:human:abc123",
  • "target_tier": 2
}

Response samples

Content type
application/json
{
  • "org_did": "did:human:org456",
  • "previous_tier": 1,
  • "governance_tier": 2,
  • "founder_count": 3,
  • "provenance_id": "prov_789"
}

Initiate a Quorum Change Proposal

Empower organizational founders with the ability to propose pivotal changes in governance. This endpoint facilitates the creation of proposals for adding or removing founders, adjusting quorum thresholds, or even dissolving the organization. It's a crucial mechanism for dynamic and secure decision-making within decentralized environments.

Request Body schema: application/json
required
change_type
required
string
Enum: "add_founder" "remove_founder" "change_threshold" "dissolve"

The type of change being proposed

proposed_by
required
string

DID of the founder proposing the change

object
expires_in_hours
integer

Proposal expiration time in hours

signature
string

Valid Ed25519 signature over the proposal payload

Responses

Request samples

Content type
application/json

Proposing the addition of a new founder to the organization

{
  • "change_type": "add_founder",
  • "proposed_by": "did:human:12345",
  • "payload": {
    },
  • "expires_in_hours": 48,
  • "signature": "base64-encoded-signature"
}

Response samples

Content type
application/json
null

Approve Organization Proposal

Navigate the intricate dance of consensus within the HUMAN network by approving proposals that shape the future of your organization. This endpoint not only records an approval but auto-executes the proposal once the required threshold is met, embedding the decision into the immutable ledger of provenance.

Request Body schema: application/json
required
One of
approver_did
required
string^did:human:.*$

Decentralized Identifier of the approver.

signature
required
string

Base64 encoded Ed25519 signature over the proposal payload.

Responses

Request samples

Content type
application/json

An example of a founder approving a proposal.

{
  • "approver_did": "did:human:founder123",
  • "signature": "dGVzdFNpZ25hdHVyZQ=="
}

Response samples

Content type
application/json
null

Summaries

Retrieve AI-generated audit summaries

Dive into the AI's lens on your organization with this endpoint. It delivers curated summaries generated by our Audit Summarizer Agent, helping you understand the intricate details of your organizational activities. This service empowers users by providing insights that can guide strategic decision-making.

Responses

Response samples

Content type
application/json

An example response where the organization 'acme' reviews its recent audit summaries.

{
  • "data": [
    ]
}

Retention

Retrieve retention policies for organization

Discover the retention periods your organization has set for its data tiers. By understanding these configurations, you can better align your data management strategies with organizational policies and compliance requirements.

Responses

Response samples

Content type
application/json

An organization with hot tier retention only.

{
  • "org_did": "did:haio:acme",
  • "retention_days_hot": 30,
  • "retention_days_warm": null,
  • "retention_days_cold": null,
  • "tiers_implemented": [
    ]
}

Reports

Retrieve Pre-built Audit Report Catalog

Unveil the hidden narratives behind your operations with HUMAN's pre-built audit report catalog. This endpoint grants you a gateway to a curated collection of insightful reports, each designed to shed light on the orchestration of human and AI activities across your organization. Discover patterns, enhance transparency, and drive informed decisions.

Responses

Response samples

Content type
application/json

A glimpse into the diverse range of audit reports available.

{
  • "data": [
    ]
}

Retrieve detailed audit report data

Delve into the intricate details of your organization's decision-making footprint. This endpoint executes a selected pre-built audit report, providing insights on delegation, trust changes, autonomy ratios, and connector usage. Use this tool to ensure transparency and governance in your human-AI interactions.

Responses

Response samples

Content type
application/json

Example of a delegation usage report for acme org.

{
  • "report_id": "delegation-usage",
  • "generated_at": "2023-10-01T12:00:00Z",
  • "period_days": 30,
  • "org_did": "did:example:acme",
  • "row_count": 150,
  • "data": [
    ]
}

Generate compliance activity report

Dive into the depths of your organization's compliance activities with this endpoint, which meticulously crafts a report detailing event occurrences over a specified time window. This ensures accountability and transparency, painting a clear picture of your operational integrity.

Request Body schema: application/json
required
start_date
string <date-time>

The start date for the report window. Only events from this date forward will be included.

end_date
string <date-time>

The end date for the report window. Only events up to this date will be included.

report_type
required
string
Enum: "summary" "detailed"

The type of report to generate. 'summary' provides a high-level overview, while 'detailed' offers in-depth insights.

Responses

Request samples

Content type
application/json

Generate a summary report for the first quarter of the year.

{
  • "start_date": "2023-01-01T00:00:00Z",
  • "end_date": "2023-03-31T23:59:59Z",
  • "report_type": "summary"
}

Response samples

Content type
application/json

A successful generation of a summary report showing event counts.

{
  • "report_type": "summary",
  • "generated_at": "2023-10-01T12:00:00Z",
  • "window": {
    },
  • "counts_by_event_type": {
    }
}

Export

Export audit events in various formats

Dive into the rich history of your organization's decisions with the ability to export audit events in CSV or JSON format. This endpoint empowers compliance and oversight by offering a comprehensive view of critical actions taken within your organization. Understand the provenance of your decisions and ensure accountability at every step.

Responses

Response samples

Content type
application/json

A JSON response containing a list of audit events.

{
  • "data": [
    ],
  • "count": 1,
  • "exported_at": "2023-09-10T15:00:00Z"
}

Export Artifacts with Provenance Data

Retrieve a detailed export of your organization's artifacts, complete with provenance. This endpoint empowers organizations to track the lineage and history of each artifact, ensuring transparency and accountability in task management. Ideal for auditing and operational insights.

Responses

Response samples

Content type
application/json

A JSON export of artifacts with provenance for the organization.

{
  • "org_did": "did:human:acme-org-123",
  • "artifacts": [
    ],
  • "exported_at": "2023-10-05T15:00:00Z",
  • "has_more": false,
  • "next_cursor": null
}

Billing

Audit missing billing categories

This endpoint performs a crucial audit on cloud metering events to ensure that all entries have a specified billing category. It's essential for maintaining accurate billing and reporting, helping organizations like 'Acme Corp' avoid financial discrepancies.

Responses

Response samples

Content type
application/json

Example response showing a scenario where some events are missing billing categories.

{
  • "untagged_count": 5,
  • "checked_at": "2023-10-05T14:48:00Z"
}

Retrieve Current Subscription Details

Unlock the door to your organization's billing insights with this endpoint. It seamlessly fetches the current subscription status, allowing you to explore whether you're in a free trial or a paid plan. This is essential for organizations to keep track of their subscription lifecycle and ensure continuous service.

Responses

Response samples

Content type
application/json
Example

An organization with an active subscription.

{
  • "status": "active",
  • "trial_ends_at": null,
  • "plan_name": "Professional"
}

Retrieve Available Billing Plans

Dive into the diverse world of HUMAN's billing plans. This endpoint uncovers a treasure trove of active plans, each replete with their unique entitlements. By understanding the structure of these plans, organizations can tailor their engagement with HUMAN, ensuring they select the perfect tier that aligns with their operational needs.

Responses

Response samples

Content type
application/json

An example illustrating the billing plan details for Acme Corp.

{
  • "plans": [
    ]
}

Initiate customer billing portal session

Embark on a seamless journey to manage your organization's billing preferences by starting a session with the Stripe billing portal. This endpoint ensures that your organization is properly set up to handle financial operations, providing a transparent and secure window into your billing world.

Request Body schema: application/json
required
return_url
string

URL to redirect to after session ends.

returnUrl
string

Alternative key for return_url.

Responses

Request samples

Content type
application/json

Example showing a custom return URL after billing session.

{}

Response samples

Content type
application/json
null

Retrieve organization's billing invoices

Dive into the financial heartbeat of your organization by accessing the billing invoices tied to your cryptographic identity. This endpoint is essential for organizations to keep track of their financial transactions and ensure transparency in billing processes.

Responses

Response samples

Content type
application/json
{
  • "invoices": [
    ]
}

Retrieve detailed compute billing insights

Dive into the details of your organization's compute billing usage. This endpoint empowers administrators to analyze compute costs, track resource consumption, and optimize expenses by providing granular insights into billing events. It exists to ensure transparency and promote informed decision-making within your organization.

Responses

Response samples

Content type
application/json

An example response showing detailed billing events for an organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "nextCursor": "evt_01G5T8V2YZCGT4T9B4STZ8VXW3"
}

Retrieve compute billing summary

Uncover a detailed breakdown of compute usage costs. This endpoint empowers organizations to gain insights into their resource consumption, enabling data-driven decisions on budgeting and optimization. Dive deep into per-user, per-app, and per-model analytics to visualize spending patterns.

Responses

Response samples

Content type
application/json

A snapshot of TechGuru's compute resource usage over the past month.

{
  • "period": {
    },
  • "by_user": [
    ],
  • "by_model": [
    ],
  • "by_feature": [
    ]
}

Retrieve billing limits for your organization

Discover the financial boundaries of your organization's AI orchestration with HUMAN. This endpoint reveals your session and daily API rate limits, compute markup, and plan tier caps, helping you manage costs and maximize efficiency. Whether you're a startup on a 'free' plan or an enterprise seeking limitless potential, understanding these limits is crucial for strategic planning.

Responses

Response samples

Content type
application/json
{
  • "mcp_rate_limit_per_session_per_min": 20,
  • "api_rate_limit_per_org_per_day": 100000,
  • "compute_markup_pct": 0,
  • "compute_warning_threshold_pct": 80,
  • "plan_tier_caps": {
    },
  • "org_did": "did:human:acme-org-1234"
}

Retrieve monthly compute usage by organization

Unveil your organization's compute usage story for the current month. This endpoint empowers cloud administrators to monitor resource consumption and manage billing efficiently, ensuring that usage aligns with organizational plans and authorized top-ups. Understand your usage patterns and avoid surprises by staying informed.

Responses

Response samples

Content type
application/json
{
  • "orgs": [
    ]
}

Authorize billing overage for an organization

Unlock additional billing capacity beyond preset limits with this endpoint, ensuring your organization never hits a processing ceiling. It's designed for those moments when unexpected demand is a sign of success, not a bottleneck.

Request Body schema: application/json
required
amount_usd
required
number [ 0.01 .. 10000 ]

The amount in USD to authorize for overage.

window_minutes
number [ 1 .. 1440 ]

The validity duration of the authorization in minutes.

auto_topup
boolean

If true, enables automatic top-up when balance is low.

Responses

Request samples

Content type
application/json

An example where the organization authorizes a $500 overage for 120 minutes with auto top-up enabled.

{
  • "amount_usd": 500,
  • "window_minutes": 120,
  • "auto_topup": true
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "org_did": "did:org:acme",
  • "authorized_topup_usd": 500,
  • "auto_topup_enabled": true,
  • "expires_at": "2023-10-23T16:00:00Z"
}

Scheduling

Retrieve Scheduled Agent Tasks

Unlock a world of precision with the HUMAN platform's schedule viewer. This endpoint reveals the heartbeat of your automated operations, providing a clear view of when each agent is set to act next. It exists to empower proactive management and seamless orchestration of tasks. Hone your command over the Command Plane with this insightful glance into your agents' futures.

Responses

Response samples

Content type
application/json

A snapshot of Acme Corporation's agent schedules, offering a glimpse into their strategic task deployment.

{
  • "data": [
    ]
}

Update an Agent's Scheduled Tasks

Empower your AI agents by updating their task schedules with precision and ease. This endpoint allows you to set or clear a recurring task schedule using a familiar cron syntax, ensuring your agents operate at the right time, every time.

Request Body schema: application/json
required
schedule_cron
required
string or null

A valid cron expression for task scheduling. Set to null to clear existing schedule.

Responses

Request samples

Content type
application/json

Schedule the agent to run data processing every Monday at 3 AM.

{
  • "schedule_cron": "0 3 * * 1"
}

Response samples

Content type
application/json
null

Remove agent's scheduled tasks

In the world of ever-adaptive AI, agents must evolve. This endpoint clears the scheduled tasks for a given agent, ensuring they are primed for new missions. By removing outdated schedules, it empowers organizations to dynamically reassign resources as their strategies shift.

Responses

Response samples

Content type
application/json
{
  • "agent_did": "did:human:123456789abcdefghi",
  • "updated_at": "2023-10-05T14:48:00.000Z"
}

Task Control

Pause an agent's task execution

In the dynamic landscape of Human-AI orchestration, there are times when an agent's activities need to be paused for strategic realignment or resource management. This endpoint empowers administrators to pause an agent's task execution, ensuring that only relevant and prioritized tasks continue in the HUMAN ecosystem.

Responses

Response samples

Content type
application/json

An example where an agent with DID 'did:example:123456789' is paused successfully.

{
  • "agentDid": "did:example:123456789",
  • "status": "paused"
}

ControlPlane

Retrieve recent decision events for an agent

Uncover the trail of decisions governed by HUMAN's sophisticated orchestration, as this endpoint unveils recent decision events associated with a specific agent. Whether you're monitoring task progress or conducting audits, these events offer a window into the agent's operational history, ensuring transparency and accountability.

Responses

Response samples

Content type
application/json
null

Retrieve diagnostics history for an organization

Explore the historical diagnostics events of your organization within the HUMAN platform. This endpoint empowers you to audit and trace past events, ensuring transparency and accountability in your AI orchestration. Utilize pagination to navigate large datasets effortlessly.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve incidents from control plane

Navigate the complexities of your organization's incident history with precision. This endpoint offers a window into the incidents registered in the control plane, filtered by organizational identity, status, and severity. By analyzing these incidents, organizations can fine-tune their strategies, ensuring smoother operations and fortified defenses.

Responses

Response samples

Content type
application/json

An organization reviews their latest incidents to adjust their response strategies.

{
  • "data": [
    ],
  • "hasMore": false,
  • "nextCursor": null
}

Retrieve Execution Records for Organization

Dive into the orchestration of AI and human tasks with detailed execution records. This endpoint empowers organizations by retrieving the history of task executions, allowing for insightful analysis and optimization of processes. By filtering through status and surface, organizations can pinpoint specific operations and evaluate their effectiveness.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve execution details by ID

Unlock the insights of your task orchestration by fetching detailed execution data through this endpoint. It bridges the gap between human and AI efforts, providing a comprehensive view of your operation's journey from start to finish. Trace every step, understand the status, and connect with the agents involved, making this endpoint your window into the orchestration process.

Responses

Response samples

Content type
application/json

Fetching an execution record for Acme Corp, including details of a linked asynchronous task.

{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "execution_id": "exec-789",
  • "org_did": "did:human:acme-corp",
  • "incident_id": "incident-001",
  • "surface": "web",
  • "status": "completed",
  • "started_at": "2023-10-01T08:00:00Z",
  • "completed_at": "2023-10-01T09:00:00Z",
  • "metadata": {
    },
  • "created_at": "2023-09-28T07:00:00Z",
  • "updated_at": "2023-10-01T09:05:00Z",
  • "async_execution": {
    }
}

Update Device Metadata Seamlessly

Enhance your device management by updating specific metadata properties effortlessly. This endpoint allows organizations to refine device configurations, such as setting or clearing the intent dispatch URL, which is crucial for diagnostic probes. By keeping your device metadata up-to-date, you maintain seamless command plane operations.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json

Set the intent dispatch URL for diagnostics.

{}

Response samples

Content type
application/json
{}

Assemble audit decisions for an organization

This endpoint meticulously assembles audit decisions, weaving together a tapestry of organizational insights. It ensures every decision is documented with precision, offering a transparent view of actions taken within the HUMAN platform. This orchestration is essential for maintaining accountability and trust in automated processes.

Responses

Response samples

Content type
application/json

A successful response indicating the number of decisions assembled and the timestamp.

{
  • "upserted": 42,
  • "assembled_at": "2023-10-15T10:00:00Z"
}

Create a recurring Workbench investigation template

In the intricate dance of human and AI collaboration, maintaining oversight is crucial. This endpoint allows you to save configurations for recurring investigations within the Workbench, ensuring consistent monitoring and analysis. By setting entry points and filters, you can automate the oversight process, harnessing the power of data to drive informed decisions.

Request Body schema: application/json
required
name
required
string

A unique name for the investigation template.

owner_passport_id
required
string

The Passport ID of the template owner.

entry_point_type
required
string

The type of entry point for the investigation.

object

A JSON object detailing filter configurations.

investigation_mode
string

The mode of investigation, defaults to 'ops'.

Responses

Request samples

Content type
application/json

A typical configuration for a compliance audit.

{
  • "name": "Compliance Audit Q1",
  • "owner_passport_id": "passport:12345",
  • "entry_point_type": "financial",
  • "filter_config": {
    },
  • "investigation_mode": "ops"
}

Response samples

Content type
application/json
{
  • "template_id": "wbtpl-1234567890"
}

IncidentManagement

Retrieve incidents from control plane

Navigate the complexities of your organization's incident history with precision. This endpoint offers a window into the incidents registered in the control plane, filtered by organizational identity, status, and severity. By analyzing these incidents, organizations can fine-tune their strategies, ensuring smoother operations and fortified defenses.

Responses

Response samples

Content type
application/json

An organization reviews their latest incidents to adjust their response strategies.

{
  • "data": [
    ],
  • "hasMore": false,
  • "nextCursor": null
}

Incident Management

Create and escalate incident for review

In the ever-evolving landscape of digital operations, the ability to swiftly identify and manage incidents is crucial. This endpoint empowers organizations to register new incidents, offering an opportunity for automatic escalation to human review if the incident's severity demands it. With a focus on both speed and accuracy, this API ensures that no critical event goes unnoticed, providing peace of mind and operational resilience.

Request Body schema: application/json
required
org_did
required
string

Decentralized Identifier (DID) of the organization

title
required
string

A brief title summarizing the incident

scan_id
string or null

Identifier for the scan that detected the incident

source_event_id
string or null

ID of the originating event triggering this incident

incident_type
string
Default: "anomaly"

Type classification of the incident

severity
string
Default: "medium"
Enum: "low" "medium" "high" "critical"

Severity level of the incident

description
string or null

Detailed description of the incident

object

Estimated impact scope of the incident

proposed_actions
Array of strings

List of actions proposed to mitigate the incident

object

Raw data associated with the incident

created_by_agent
string or null

Agent ID responsible for creating the incident

request_escalation
boolean
Default: false

Indicator whether manual escalation to human review is requested

skip_auto_escalation
boolean
Default: false

Flag to skip automatic escalation based on severity

Responses

Request samples

Content type
application/json

Registers an incident with minimal required fields

{
  • "org_did": "did:example:acme",
  • "title": "Unexpected spike in CPU usage",
  • "severity": "high",
  • "request_escalation": true
}

Response samples

Content type
application/json

The CPU usage spiked unexpectedly, potentially causing performance degradation.

null

Update and escalate incident status seamlessly

This endpoint breathes life into incident management by allowing seamless status updates and escalations for incidents. It ensures that your organization's response to incidents is swift, keeping security tight and operations smooth. Dive into the orchestration of human and AI with a single call.

Request Body schema: application/json
required
status
string
Enum: "open" "investigating" "escalated" "resolved" "dismissed"

The status to update the incident to.

severity
integer

The severity level of the incident.

resolution_notes
string

Notes detailing the resolution process, required if status is 'resolved' or 'dismissed'.

Responses

Request samples

Content type
application/json

Escalate an incident to human review with detailed notes.

{
  • "status": "escalated",
  • "resolution_notes": "Additional review required due to complexity."
}

Response samples

Content type
application/json

Marks the incident as resolved with notes.

{
  • "id": "inc_12345",
  • "status": "resolved",
  • "resolved_by": "passport_67890",
  • "resolved_at": "2023-10-12T07:20:50.52Z",
  • "resolution_notes": "Issue resolved after resetting the server."
}

Retrieve summary of incident metrics

Dive into the heart of your organization’s incident handling with this endpoint. It provides a comprehensive summary of incident metrics, filtered by severity and status, empowering you to understand patterns and improve response strategies. This endpoint exists to ensure that organizations can proactively manage and mitigate incidents before they escalate.

Responses

Response samples

Content type
application/json

Acme Corp’s incident metrics summary shows a balanced view of incidents by severity and status.

{
  • "org_did": "did:example:acme",
  • "total_count": 42,
  • "by_severity": {
    },
  • "by_status": {
    },
  • "breakdown": [
    ]
}

Suggest remediation for an incident

This endpoint crafts a thoughtful remediation suggestion for a given incident, weaving together AI predictions and human insights. It empowers organizations to address incidents with precision, ensuring safety and compliance through seamless task orchestration.

Request Body schema: application/json
required
enqueue_agent_trigger
boolean

Flag to trigger an agent if true.

Responses

Request samples

Content type
application/json
Example

A request to suggest remediation without agent trigger.

{
  • "enqueue_agent_trigger": false
}

Response samples

Content type
application/json
{
  • "incident_id": "12345",
  • "mode": "automatic",
  • "steps": [
    ]
}

Link External Issue to Incident

In the high-stakes world of incident management, every moment counts. This endpoint empowers you to link an external issue from popular trackers like Jira or GitHub directly to an incident, ensuring seamless integration and comprehensive incident resolution history.

Request Body schema: application/json
required
provider
required
string
Enum: "linear" "jira" "github"

The external provider where the issue is tracked

external_key
required
string

A stable identifier for the issue within the external tracker

issue_url
required
string <uri>

The direct URL to the issue in the external tracker

Responses

Request samples

Content type
application/json

Linking a Jira issue to an incident

{}

Response samples

Content type
application/json
null

Incidents

Retrieve detailed incident information

Dive into the heart of incident management with this endpoint, which fetches not only the incident's core details but also a tapestry of linked approvals and external issues. By providing comprehensive insights into each incident, it empowers organizations to understand and resolve issues with precision and efficiency.

Responses

Response samples

Content type
application/json

An example response showing a complete incident with associated approval requests and external issues.

{
  • "id": "incident-12345",
  • "title": "Network Outage in Data Center",
  • "status": "Investigating",
  • "linked_approvals": [
    ],
  • "linked_external_issues": [],
  • "workbench_links": {
    }
}

Retrieve deduplicated partner incident feed

Gain insights into marketplace incidents impacting your assets with this endpoint. By leveraging your Passport, it filters and summarizes incidents, providing a concise view of issues that matter most to your organization. Discover the root causes and suggested fixes quickly, ensuring you can take prompt action.

Responses

Response samples

Content type
application/json

Retrieves the incident feed for a publisher with Passport ID 'publisher-123'.

{
  • "publisher_id": "publisher-123",
  • "generated_at": "2023-10-15T12:34:56Z",
  • "data": [
    ]
}

Subscription

Retrieve Current Subscription Details

Unlock the door to your organization's billing insights with this endpoint. It seamlessly fetches the current subscription status, allowing you to explore whether you're in a free trial or a paid plan. This is essential for organizations to keep track of their subscription lifecycle and ensure continuous service.

Responses

Response samples

Content type
application/json
Example

An organization with an active subscription.

{
  • "status": "active",
  • "trial_ends_at": null,
  • "plan_name": "Professional"
}

Plans

Retrieve Available Billing Plans

Dive into the diverse world of HUMAN's billing plans. This endpoint uncovers a treasure trove of active plans, each replete with their unique entitlements. By understanding the structure of these plans, organizations can tailor their engagement with HUMAN, ensuring they select the perfect tier that aligns with their operational needs.

Responses

Response samples

Content type
application/json

An example illustrating the billing plan details for Acme Corp.

{
  • "plans": [
    ]
}

Stripe

Initiate customer billing portal session

Embark on a seamless journey to manage your organization's billing preferences by starting a session with the Stripe billing portal. This endpoint ensures that your organization is properly set up to handle financial operations, providing a transparent and secure window into your billing world.

Request Body schema: application/json
required
return_url
string

URL to redirect to after session ends.

returnUrl
string

Alternative key for return_url.

Responses

Request samples

Content type
application/json

Example showing a custom return URL after billing session.

{}

Response samples

Content type
application/json
null

Invoices

Retrieve organization's billing invoices

Dive into the financial heartbeat of your organization by accessing the billing invoices tied to your cryptographic identity. This endpoint is essential for organizations to keep track of their financial transactions and ensure transparency in billing processes.

Responses

Response samples

Content type
application/json
{
  • "invoices": [
    ]
}

Workflow

Batch Create Tasks for Organization

Efficiently initiate multiple tasks within an organization at once, saving time and effort. This endpoint is a crucial tool for companies seeking to optimize task management at scale, ensuring all tasks are properly prioritized and tracked.

Request Body schema: application/json
required
required
Array of objects
object

Responses

Request samples

Content type
application/json

An example showing task creation with priority and callback URL.

{
  • "tasks": [
    ],
  • "batch_options": {}
}

Response samples

Content type
application/json
{
  • "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
  • "task_ids": [
    ]
}

Create workflow from Companion suggestion

This endpoint empowers organizations to transform AI-driven insights from the HUMAN Companion into executable workflows. By bridging AI suggestions with organizational processes, it orchestrates a seamless integration ensuring efficiency and innovation.

Request Body schema: application/json
required
suggested_intent
string

AI suggested intent for the workflow.

intent_brief_id
string

Optional ID of an existing intent brief.

Responses

Request samples

Content type
application/json

An example where a new workflow is suggested by the AI companion.

{
  • "suggested_intent": "Automate invoice processing",
  • "intent_brief_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json

A successful response with a new workflow manifest and IDs.

{
  • "manifest": {
    },
  • "intent_brief_id": "123e4567-e89b-12d3-a456-426614174000",
  • "resolution_plan_id": "plan-9876",
  • "source": "intent_scaffold"
}

Deactivate a workflow by ID

In the dynamic world of task management, workflows often need to be paused or revisited. This endpoint allows you to deactivate a workflow, transitioning it to a 'draft' state. By doing so, teams can refine tasks without impacting the live environment, ensuring meticulous quality control before reactivation.

Request Body schema: application/json
required
note
string

An optional note providing context or reasoning for the deactivation.

Responses

Request samples

Content type
application/json

Deactivating a workflow with a note.

{
  • "note": "Pausing workflow for quarterly review."
}

Response samples

Content type
application/json
{
  • "id": "workflow-123",
  • "orgId": "acme-corp",
  • "name": "Invoice Processing",
  • "lifecycleState": "draft",
  • "updatedAt": "2023-10-05T14:48:00.000Z"
}

Resolve Workflow Capabilities

This endpoint is the conductor in an orchestra of capabilities, harmonizing the skills required for each step in a workflow. It ensures that only the most suitable connectors are employed, optimizing efficiency and precision in task execution.

Request Body schema: application/json
required
include_trace
boolean

Whether to include trace information for debugging.

Responses

Request samples

Content type
application/json

An example where trace information is requested.

{
  • "include_trace": true
}

Response samples

Content type
application/json

A successful resolution of capabilities for a workflow step.

{
  • "resolutions": [
    ]
}

Test Workflow Execution

Initiate a test run of a specific workflow, allowing you to simulate different execution modes to evaluate workflow logic before full deployment. This endpoint empowers organizations to ensure their workflows operate as expected, mitigating risks in live environments.

Request Body schema: application/json
required
mode
required
string
Enum: "dry_run" "sample_data" "live_safe"

Execution mode for the workflow test. Defaults to 'dry_run' if not specified.

Responses

Request samples

Content type
application/json

A test execution in 'dry_run' mode

{
  • "mode": "dry_run"
}

Response samples

Content type
application/json
{
  • "mode": "dry_run",
  • "steps": [
    ],
  • "duration_ms": 125,
  • "lifecycle_state": "draft"
}

Import and draft external workflow

Breathe life into your workflow library by importing external agent or workflow definitions. This endpoint empowers organizations to craft an initial draft of a builder workflow, ensuring seamless integration with existing processes. Whether you're migrating with capability overrides or specifying platform hints, this operation is your gateway to a refined orchestration setup.

Request Body schema: application/json
required
payload
required
string

Base64 encoded agent or workflow definition.

platform_hint
string

Optional hint about the target platform.

object

Optional per-step capability overrides.

name
string

Optional workflow name. Defaults to 'Imported workflow'.

Responses

Request samples

Content type
application/json

Import a basic workflow with no platform hint or overrides.

{
  • "payload": "c29tZS1iYXNlNjQtcGF5bG9hZA==",
  • "name": "Invoice Processor"
}

Response samples

Content type
application/json
{
  • "workflow_id": "wf_12345",
  • "builder_url": "https://console.haio.run/builder/wf_12345",
  • "rung": 2,
  • "step_summary": {
    },
  • "warnings": [
    ],
  • "suggested_connectors": [
    ]
}

Tasks

Create a new workforce task for an organization

This endpoint empowers internal and HumanOS callers to create tasks that are seamlessly integrated into the workforce task queue. By providing a programmatic interface, it allows for the automation and orchestration of task assignments, ensuring that tasks are efficiently routed and managed according to the organization's needs.

Request Body schema: application/json
required
task_type
required
string

The type of task to be created, defining its nature and handling.

priority
string
Enum: "high" "normal" "low"

The priority level of the task, influencing its position in the queue.

sla_minutes
integer >= 0

Service Level Agreement time in minutes, indicating the expected completion time.

source
string
Default: "api"

The origin of the task creation request.

payload
object

Additional data relevant to the task, specific to the task type.

required_caps
Array of strings

Responses

Request samples

Content type
application/json

Creating a normal priority task for invoice processing

{
  • "task_type": "invoice_processing",
  • "priority": "normal",
  • "sla_minutes": 30,
  • "source": "api",
  • "payload": {
    },
  • "required_caps": [
    ]
}

Response samples

Content type
application/json
{
  • "task_id": "task-67890",
  • "queue_id": "queue-123",
  • "assignment_id": null,
  • "worker_id": null,
  • "status": "queued"
}

Retrieve workforce tasks for an organization

Navigate the dynamic world of task management by retrieving a list of tasks for a specified organization. This endpoint empowers you to filter tasks based on status, priority, and queue, while offering seamless pagination to traverse large datasets with ease.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "eyJ2IjoyLCJwciI6MiwgImNyZWF0ZWRfYXQiOiIyMDIzLTEwLTAxVDEyOjAwOjAwWiIsICJ0YXNrX2lkIjoidGFzay0xMjMifQ=="
}

Retrieve task outcome history

Uncover the complete history of a task's outcomes, providing a transparent view into its provenance timeline. This endpoint offers organizations a way to trace the evolution of a task, ensuring clarity and accountability in workforce management.

Responses

Response samples

Content type
application/json

Retrieve all outcomes for task ID 123 from organization 'acme'.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Submit results for a workforce task

In the bustling world of HUMAN orchestration, submitting your task results is the final triumphant step. This endpoint ensures that your contributions to the workforce are recorded, verified, and directed towards the next stage of processing. It embodies the harmonious collaboration between human workers and AI, ensuring each task is completed with transparency and efficiency.

Request Body schema: application/json
required
result
required
object

The result data of the task, encapsulating the output produced by the worker.

time_spent
integer

Time spent by the worker on this task, in minutes.

difficulty_rating
integer

A subjective rating of task difficulty provided by the worker, on a scale from 1 to 5.

Responses

Request samples

Content type
application/json

Submission of results for processing an invoice in the 'acme' organization.

{
  • "result": {
    },
  • "time_spent": 45,
  • "difficulty_rating": 3
}

Response samples

Content type
application/json
{
  • "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  • "status": "submitted",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "next_step": "quality_review"
}

Retrieve task details for a workforce

Explore the inner workings of your organization by retrieving detailed information about a specific workforce task. This endpoint not only reveals the task's status but also uncovers its journey through the organizational queue and current assignment state, providing a comprehensive view of task orchestration.

Responses

Response samples

Content type
application/json

A scenario where a task has been completed by a worker.

{
  • "task_id": "task-123",
  • "org_id": "org-acme",
  • "queue_name": "Invoice Processing",
  • "assignment_id": "assign-456",
  • "worker_id": "worker-789",
  • "assignment_state": "completed",
  • "assigned_at": "2023-10-10T14:48:00Z",
  • "started_at": "2023-10-10T14:50:00Z",
  • "completed_at": "2023-10-10T15:00:00Z"
}

Workforce Management

Retrieve workforce tasks for an organization

Navigate the dynamic world of task management by retrieving a list of tasks for a specified organization. This endpoint empowers you to filter tasks based on status, priority, and queue, while offering seamless pagination to traverse large datasets with ease.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "eyJ2IjoyLCJwciI6MiwgImNyZWF0ZWRfYXQiOiIyMDIzLTEwLTAxVDEyOjAwOjAwWiIsICJ0YXNrX2lkIjoidGFzay0xMjMifQ=="
}

Remove a workforce routing rule

In the ever-evolving landscape of AI-driven task management, maintaining an agile and precise routing system is crucial. This endpoint allows organizations to surgically remove outdated or incorrect routing rules, ensuring optimal workflow orchestration and AI safety. By deleting a rule, you streamline your task routing, fostering efficiency and accuracy.

Responses

Response samples

Content type
application/json

The routing rule with ID 'rule-12345' for organization 'org-67890' was successfully deleted.

null

Register a new worker in organization

This endpoint integrates a human workforce into the HUMAN platform by associating a cryptographic identity, known as a Passport DID, with an organization. This empowers enterprises to harness verified human skills, ensuring efficient task routing and provenance tracking.

Request Body schema: application/json
required
passport_did
required
string

Decentralized Identifier (DID) representing the worker's cryptographic identity.

workforce_roles
Array of strings

List of roles assigned to the worker within the organization.

capability_refs
Array of strings[ items^capability:// ]

References to specific capabilities the worker possesses.

max_concurrent
integer
Default: 5

Maximum number of concurrent tasks the worker can handle.

Responses

Request samples

Content type
application/json

Illustrates adding a new worker, John Doe, with specific roles and capabilities.

{
  • "passport_did": "did:example:123456789abcdefghi",
  • "workforce_roles": [
    ],
  • "capability_refs": [
    ],
  • "max_concurrent": 3
}

Response samples

Content type
application/json
{
  • "worker_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "org_id": "org-acme",
  • "passport_did": "did:example:123456789abcdefghi",
  • "workforce_roles": [
    ],
  • "capability_refs": [
    ],
  • "status": "active",
  • "max_concurrent": 3
}

Update a worker's profile in an organization

Modify the attributes of a worker within your organization, seamlessly aligning skills and roles. This endpoint empowers organizations to dynamically adapt their workforce capabilities in response to evolving needs, ensuring optimal efficiency and productivity.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Retrieve workforce task assignments

Discover the orchestration of human and AI efforts by viewing task assignments in your organization. This endpoint empowers workers by displaying their specific tasks, while administrators can observe all assignments across the workforce, enhancing transparency and operational efficiency.

Responses

Response samples

Content type
application/json

An example response showing task assignments for workers in the Acme Corporation.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "assigned_at",
  • "hasMore": false
}

Outcomes

Retrieve task outcome history

Uncover the complete history of a task's outcomes, providing a transparent view into its provenance timeline. This endpoint offers organizations a way to trace the evolution of a task, ensuring clarity and accountability in workforce management.

Responses

Response samples

Content type
application/json

Retrieve all outcomes for task ID 123 from organization 'acme'.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Queue Management

Update workforce queue details

Refine your organization's task orchestration by updating key attributes of a workforce queue. Whether enhancing the queue's purpose with a fresh name or adjusting its visibility, this endpoint empowers you to keep task routing aligned with evolving business needs.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Task Routing

Retrieve organization's task routing rules

In the bustling world of HUMAN's orchestration, routing rules are the silent conductors ensuring tasks land in the right queues. This API endpoint unveils the orchestration within your organization, mapping each task type to its designated queue, ensuring efficiency and safety in human-AI collaboration.

Responses

Response samples

Content type
application/json

A snapshot of routing rules for an organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": false
}

Create or update task routing rule

Define how tasks are routed by associating them with default queues within your organization. This endpoint empowers automated task distribution, ensuring efficiency and alignment with organizational workflows. By crafting these rules, you enable seamless orchestration between human and AI capabilities, optimizing task management.

Request Body schema: application/json
required
task_type
required
string

The type of task this rule applies to.

default_queue_id
required
string <uuid>

The queue ID where tasks of this type are routed by default.

requires_human
boolean

Indicates if human intervention is required for this task type.

reviewer_count
integer

Number of reviewers needed for tasks of this type.

escalation_policy
object

Policy dictating task escalation parameters.

Responses

Request samples

Content type
application/json

Example of setting a routing rule for invoice processing tasks.

{
  • "task_type": "invoice_processing",
  • "default_queue_id": "8f8c1d1e-1e1b-4b8a-b6e4-2b3a5e6dbe1e",
  • "requires_human": true,
  • "reviewer_count": 2,
  • "escalation_policy": {
    }
}

Response samples

Content type
application/json
{
  • "org_id": "acme-corp",
  • "task_type": "invoice_processing",
  • "default_queue_id": "8f8c1d1e-1e1b-4b8a-b6e4-2b3a5e6dbe1e",
  • "requires_human": true,
  • "reviewer_count": 2,
  • "escalation_policy": {
    }
}

Route tasks with HumanOS AI orchestration

This endpoint is a gateway to orchestrate tasks efficiently using the HumanOS routing capabilities. By combining AI-driven insights with human skills, it ensures tasks are assigned to the most suitable agents. This promotes seamless interaction between humans and AI, optimizing task outcomes.

Request Body schema: application/json
required
task_id
required
string

Unique identifier for the task

task_type
required
string

Type of task to be routed

priority
string
Enum: "low" "medium" "high"

Priority level of the task

metadata
object

Additional data related to the task

Responses

Request samples

Content type
application/json

Routing a high-priority customer support task

{
  • "task_id": "task-12345",
  • "task_type": "customer_support",
  • "priority": "high",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "status": "routed",
  • "agent_id": "agent-98765"
}

Match Capabilities for Task Routing

Efficiently orchestrate tasks by matching required capabilities to available humans and agents. This endpoint leverages a sophisticated algorithm to ensure that the right skills are applied to the right tasks, enhancing productivity and ensuring AI safety.

Request Body schema: application/json
required
required_capabilities
required
Array of strings

List of capability IDs required for the task.

org_id
required
string

The organization ID where the task is to be routed.

min_confidence
number [ 0 .. 1 ]
Default: 0.5

Minimum confidence level for matching capabilities.

include_humans
boolean
Default: true

Whether to include human resources in the match.

include_agents
boolean
Default: true

Whether to include AI agents in the match.

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of matches to return.

match_strategy
string
Default: "exact"
Enum: "exact" "semantic" "hybrid"

Strategy to use for matching capabilities.

task_description
string

Description of the task, required if using semantic or hybrid strategy.

task_id
string
Default: "inline"

Unique identifier for the task.

Responses

Request samples

Content type
application/json

A request to match capabilities with a minimum confidence of 0.7 in the 'acme' organization using an exact match strategy.

{
  • "required_capabilities": [
    ],
  • "org_id": "org_acme",
  • "min_confidence": 0.7,
  • "include_humans": true,
  • "include_agents": true,
  • "limit": 10,
  • "match_strategy": "exact"
}

Response samples

Content type
application/json

An example of a successful match with humans and agents for invoice processing.

{
  • "humans": [
    ],
  • "agents": [
    ],
  • "capability_gap": false,
  • "query": {
    },
  • "matched_count": 3,
  • "match_strategy_used": "exact",
  • "weakest_link_score": 0.85,
  • "threshold_used": 0.7,
  • "routed": true,
  • "resolved_canonical": [
    ],
  • "semantic_skipped": false
}

Routing

Update Workforce Routing Rule Details

Fine-tune the orchestration of tasks within your organization by updating a specific workforce routing rule. This endpoint allows you to modify key attributes of a routing rule, ensuring that tasks are efficiently managed and aligned with your organization's evolving needs.

Request Body schema: application/json
required
default_queue_id
string

The ID of the default queue to assign tasks to. Must belong to the organization.

requires_human
boolean

Flag indicating if human intervention is required for tasks routed by this rule.

reviewer_count
integer

The number of reviewers required for tasks.

escalation_policy
object

JSON object detailing the escalation policy.

Responses

Request samples

Content type
application/json

Example showcasing updating default queue and reviewer count for a rule.

{
  • "default_queue_id": "queue-1234",
  • "reviewer_count": 2
}

Response samples

Content type
application/json
{
  • "rule_id": "rule-5678",
  • "org_id": "acme",
  • "default_queue_id": "queue-1234",
  • "requires_human": true,
  • "reviewer_count": 2,
  • "escalation_policy": { }
}

Route and Update Signal Verdict

This endpoint empowers organizations to dynamically update the verdict of a signal and adjust its routing metadata. It serves as a crucial touchpoint for ensuring signals are processed accurately and efficiently within the HUMAN Protocol, reflecting real-time decision-making and task management.

Request Body schema: application/json
required
verdict
string
Enum: "pending" "approved" "suppressed" "routed"

The new verdict for the signal.

route_action
string

Action taken for routing the signal.

metadata_patch
object

Partial metadata update for the signal.

Responses

Request samples

Content type
application/json

Example showing how to approve a signal and set a route action.

{
  • "verdict": "approved",
  • "route_action": "escalate",
  • "metadata_patch": {
    }
}

Response samples

Content type
application/json
null

Retrieve routing decision details

Discover the intricate journey of a task within HUMAN's AI orchestration. This endpoint illuminates the path a task takes, revealing the decision-making intricacies and outcomes. Tracking the provenance of AI-driven processes is crucial for transparency and trust.

Responses

Response samples

Content type
application/json

Shows a successful retrieval of routing information for a task

{
  • "routing_id": "routing-123",
  • "task_id": "task-456",
  • "task_type": "invoice-processing",
  • "status": "completed",
  • "confidence": 0.95,
  • "fourth_law_triggered": false,
  • "routing_decision": "approved",
  • "pipeline_success": true,
  • "request_payload": {
    },
  • "response_payload": {
    },
  • "pipeline_stages": [
    ],
  • "created_at": "2023-10-04T14:48:00Z"
}

Retrieve routing capabilities for tasks

Uncover the harmony between AI and human skills by identifying routing capabilities tailored to your organization's needs. This endpoint orchestrates the intricate dance of task routing by fetching a curated list of capabilities based on your specified criteria, ensuring optimal skill application and AI safety.

Responses

Response samples

Content type
application/json

Retrieving a list of capabilities for the 'acme' organization with specific routing needs.

{
  • "capabilities": [
    ],
  • "count": 1,
  • "org_slug": "acme",
  • "overlay": "canonical + org-scoped"
}

Routing Rules

Remove a workforce routing rule

In the ever-evolving landscape of AI-driven task management, maintaining an agile and precise routing system is crucial. This endpoint allows organizations to surgically remove outdated or incorrect routing rules, ensuring optimal workflow orchestration and AI safety. By deleting a rule, you streamline your task routing, fostering efficiency and accuracy.

Responses

Response samples

Content type
application/json

The routing rule with ID 'rule-12345' for organization 'org-67890' was successfully deleted.

null

Human Resources

Register a new worker in organization

This endpoint integrates a human workforce into the HUMAN platform by associating a cryptographic identity, known as a Passport DID, with an organization. This empowers enterprises to harness verified human skills, ensuring efficient task routing and provenance tracking.

Request Body schema: application/json
required
passport_did
required
string

Decentralized Identifier (DID) representing the worker's cryptographic identity.

workforce_roles
Array of strings

List of roles assigned to the worker within the organization.

capability_refs
Array of strings[ items^capability:// ]

References to specific capabilities the worker possesses.

max_concurrent
integer
Default: 5

Maximum number of concurrent tasks the worker can handle.

Responses

Request samples

Content type
application/json

Illustrates adding a new worker, John Doe, with specific roles and capabilities.

{
  • "passport_did": "did:example:123456789abcdefghi",
  • "workforce_roles": [
    ],
  • "capability_refs": [
    ],
  • "max_concurrent": 3
}

Response samples

Content type
application/json
{
  • "worker_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "org_id": "org-acme",
  • "passport_did": "did:example:123456789abcdefghi",
  • "workforce_roles": [
    ],
  • "capability_refs": [
    ],
  • "status": "active",
  • "max_concurrent": 3
}

Assignments

Retrieve workforce task assignments

Discover the orchestration of human and AI efforts by viewing task assignments in your organization. This endpoint empowers workers by displaying their specific tasks, while administrators can observe all assignments across the workforce, enhancing transparency and operational efficiency.

Responses

Response samples

Content type
application/json

An example response showing task assignments for workers in the Acme Corporation.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "assigned_at",
  • "hasMore": false
}

Initiate a workforce assignment

Empower your workforce by starting an assignment with precision. This endpoint ensures that tasks are commenced by authorized individuals, maintaining the integrity and flow of organizational operations.

Responses

Response samples

Content type
application/json
null

Complete workforce assignment with decision

Empower your workforce with decisive closure! This endpoint allows a human worker to submit a final decision on a task, completing the assignment with clarity and precision. By enforcing explicit decision-making, it ensures transparency and accountability in task management.

Request Body schema: application/json
required
decision
required
string
Enum: "approved" "rejected" "needs_changes" "escalated"

The final decision made on the assignment.

notes
string

Additional notes required if decision is 'rejected' or 'needs_changes'.

risk_class
string

Optional risk classification for the decision.

artifacts
object

Optional artifacts related to the decision.

Responses

Request samples

Content type
application/json

Submitting an 'approved' decision for a completed task.

{
  • "decision": "approved",
  • "notes": "All criteria met. Proceed with closure.",
  • "risk_class": "low",
  • "artifacts": { }
}

Response samples

Content type
application/json
null

Matching

Match workforce based on capabilities

In a world where tasks demand the right talents, this endpoint finds workers with the exact capabilities your organization needs. By specifying required skills, you enable the HUMAN platform to orchestrate a match that optimizes task routing, ensuring tasks are handled by the most qualified individuals.

Request Body schema: application/json
required
required
Array of objects

List of capabilities with optional minimum weights

limit
integer <= 100

Maximum number of matches to return

Responses

Request samples

Content type
application/json

Find workers with specific capabilities

{
  • "required_capabilities": [
    ],
  • "limit": 10
}

Response samples

Content type
application/json
{
  • "matches": [
    ],
  • "total_matches": 1
}

Tuning

Retrieve effective HumanOS tuning actions

In a world where AI safety and human collaboration are paramount, understanding the effective tuning actions within your HumanOS ecosystem is crucial. This endpoint empowers organizations by offering insights into the most impactful tuning actions, ensuring your AI and human agents are aligned and performing at their best.

Responses

Response samples

Content type
application/json

A list of effective tuning actions for the organization 'acme'.

{
  • "org_did": "did:human:1234567890abcdef",
  • "scope": "user",
  • "effective": [
    ],
  • "actions_considered": 5
}

Compare Tuning to Default Settings

This endpoint unveils the hidden drift between your organization's custom HumanOS tuning and the established defaults. By examining this divergence, organizations can ensure their Human-AI orchestration aligns with desired operational standards, enhancing both efficiency and safety.

Responses

Response samples

Content type
application/json

Illustrates an organization comparing their current settings with default ones.

{
  • "org_did": "did:example:acme",
  • "scope": "user",
  • "effective": {
    },
  • "defaults": {
    },
  • "drift": {
    },
  • "actions_considered": 150
}

Create a new tuning action

This endpoint empowers organizations to tailor their HumanOS interactions by registering tuning actions like setting preferences or muting sources. It's a dynamic tool for enhancing AI safety and operational precision, ensuring that actions align with organizational policies and adaptive learning strategies.

Request Body schema: application/json
required
action_type
required
string
Enum: "revert_tuning" "set_digest_mode" "mute_source" "unmute_source" "set_preference"

The type of tuning action to execute

payload
required
object

Parameters specific to the action type

scope
string
Enum: "user" "org" "team"

The scope of the tuning action

approval_request_id
string

ID for the approval request if required

expires_at
string <date-time>

The expiration time of the tuning action

Responses

Request samples

Content type
application/json

Illustrates setting a user preference within allowed parameters

{
  • "action_type": "set_preference",
  • "payload": {
    },
  • "scope": "user",
  • "expires_at": "2023-12-31T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "action_id": "tun123456",
  • "org_did": "did:human:acme",
  • "action_type": "set_preference",
  • "scope": "user",
  • "payload": {
    },
  • "expires_at": "2023-12-31T23:59:59Z",
  • "created_at": "2023-10-15T12:00:00Z"
}

Capture

Submit new capture for HUMAN orchestration

Initiate a capture process on the HUMAN platform, enabling seamless orchestration between humans and AI. This endpoint is a pivotal entry point to submit diverse data types for further processing and task routing, ensuring data integrity and provenance within a decentralized system.

Request Body schema: application/json
required
source_kind
required
string
Enum: "text" "webhook" "audio" "video" "transcript"

Identifies the type of data source being captured.

submitter_ref
string

Reference to the entity submitting the capture.

scope
string

The scope within which the capture is being made, defaults to 'org'.

intent
string

The intended outcome or purpose of the capture.

payload_ref
string

Reference to the payload data, if applicable.

payload
object

The actual data being captured.

provenance_parent_id
string

ID of the parent capture, if this is a continuation or related capture.

effective_config_keys
object

Configuration keys influencing capture processing.

enqueue_invocation
boolean

Flag indicating whether an invocation should be enqueued.

enqueue_human_call
boolean

Flag indicating whether a human call task should be queued.

invocation_task_type
string

Specifies the type of task to invoke if enqueuing.

trace_id
string

Trace identifier for tracking invocation.

invocation_input
object

Input details for the invocation task.

Responses

Request samples

Content type
application/json

Submits a text-based capture for processing by HUMAN.

{
  • "source_kind": "text",
  • "submitter_ref": "did:human:acme-agent",
  • "scope": "org",
  • "intent": "transcription",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "capture_id": "cap_123456",
  • "org_did": "did:human:acme",
  • "source_kind": "text",
  • "submitted_at": "2023-10-01T12:00:00Z",
  • "submitter_ref": "did:human:acme-agent",
  • "scope": "org",
  • "payload_ref": "ref_987654",
  • "intent": "transcription",
  • "provenance_parent_id": null,
  • "effective_config_keys": { },
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-01T12:00:00Z",
  • "invocation_enqueued": true,
  • "async_execution_id": "exe_654321",
  • "capture_invocation_error": null
}

Data Capture

Retrieve detailed capture information

Uncover the tapestry of HUMAN's orchestration by retrieving detailed information about a specific data capture. This endpoint empowers organizations to track and understand the provenance and intent of their AI and human interactions, enhancing transparency and accountability.

Responses

Response samples

Content type
application/json

Details of a capture from the 'acme' organization.

{
  • "capture_id": "12345",
  • "org_did": "did:example:acme",
  • "source_kind": "sensor",
  • "submitted_at": "2023-10-01T12:00:00Z",
  • "submitter_ref": "agent:john.doe",
  • "scope": "invoice-processing",
  • "payload_ref": "payload:98765",
  • "payload": {
    },
  • "intent": "Automated invoice processing",
  • "provenance_parent_id": "prov:67890",
  • "effective_config_keys": [
    ],
  • "created_at": "2023-09-30T10:00:00Z",
  • "updated_at": "2023-10-01T11:00:00Z"
}

Evaluation

Evaluate a Watch Cycle for Feedback

In the intricate dance between humans and AI, feedback is the music. This endpoint lets organizations capture and store evaluation feedback for a specific watch cycle, enhancing the transparency and auditability of AI decisions. By anchoring an evaluation in the distributed ledger, you ensure that your AI's decisions are not only accountable but also improvable.

Request Body schema: application/json
required
provenance_id
string

An optional identifier for provenance tracking, providing a cryptographic link to prior events.

Responses

Request samples

Content type
application/json

An evaluation including a provenance pointer for enhanced traceability

{
  • "provenance_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "evaluation_feedback_id": "789e4567-e89b-12d3-a456-426614174111",
  • "watch_id": "watch123",
  • "org_did": "did:example:acme",
  • "evaluated_at": "2023-10-01T12:34:56Z",
  • "provenance_pointer": "123e4567-e89b-12d3-a456-426614174000"
}

Watches

Retrieve details of a specific watch

Discover the intricate details of a specific HumanOS watch. This endpoint reveals how tasks are orchestrated within your organization by fetching comprehensive data about a watch, including its status and schedule. It's a lens into understanding how tasks are managed and monitored, ensuring the right skills are applied at the right time.

Responses

Response samples

Content type
application/json

An example showing the details of a specific watch.

{
  • "watch_id": "watch123",
  • "org_did": "did:human:org:acme",
  • "target_ref": "task:invoice-processing",
  • "watch_kind": "realtime",
  • "owner_ref": "agent:john.doe",
  • "scope": "organization",
  • "schedule": "0 0 * * *",
  • "status": "active",
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-02T12:00:00Z"
}

Artifacts

Create a new HUMAN artifact

This endpoint allows organizations to craft and store digital artifacts, defining their type and metadata for enhanced provenance tracking. It empowers teams to maintain a transparent history of digital creations, facilitating AI collaboration with human oversight.

Request Body schema: application/json
required
artifact_type
required
string

The type of the artifact, must be a valid dot-namespace kind.

metadata
object

Metadata specific to the artifact kind.

owner_ref
string

Reference to the owner of the artifact.

schema_ref
string

Reference to the schema applicable to the artifact.

capture_id
string

Identifier for the capture session, if applicable.

title
string

A brief title for the artifact.

body
object

The actual content of the artifact.

media_type
string

Media type of the artifact content.

body_storage_ref
string

Reference for storage of large artifact content.

production
object

Production-related metadata.

created_by
object

Actor reference for the entity creating the artifact.

provenance_summary
string

A summary of the provenance action.

Responses

Request samples

Content type
application/json

This example demonstrates creating a basic artifact with essential fields.

{
  • "artifact_type": "document.invoice",
  • "metadata": {
    },
  • "owner_ref": "did:example:123456",
  • "title": "Q3 Financial Report",
  • "body": {
    },
  • "media_type": "application/json"
}

Response samples

Content type
application/json
{
  • "artifact_id": "art-xyz123",
  • "org_did": "did:example:123456",
  • "artifact_type": "document.invoice"
}

Retrieve a list of artifacts

Delve into the HUMAN platform's vast repository of artifacts, each a testimony to the collective intelligence of humans and AI. This endpoint lets you navigate through a curated list of organizational artifacts, filtered by type and lifecycle state, empowering you to track the evolution of human and AI collaboration.

Responses

Response samples

Content type
application/json

Retrieve a list of artifacts belonging to the Acme Corporation, filtered by type and state.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Update Artifact Lifecycle State

This endpoint orchestrates the delicate dance of artifact lifecycle transitions within the HUMAN platform, ensuring compliance with organizational policies. It exists to securely manage the evolution of artifacts, reflecting their journey from inception to completion, while respecting the constraints of the Fourth Law policy.

Request Body schema: application/json
required
lifecycle_state
required
string
Enum: "draft" "submitted" "approved" "rejected" "archived"

The new lifecycle state for the artifact.

approval_request_id
string

The ID of the approval request, required for certain transitions.

Responses

Request samples

Content type
application/json

Transition an artifact to the approved state with a valid approval request ID.

{
  • "lifecycle_state": "approved",
  • "approval_request_id": "approval-12345"
}

Response samples

Content type
application/json
{
  • "artifact_id": "artifact-67890",
  • "lifecycle_state": "approved",
  • "updated_at": "2023-11-01T12:45:00Z"
}

Retrieve Artifact with Provenance Details

Uncover the history and details of an artifact within the HUMAN platform. This endpoint provides not only the artifact's core data but also its provenance and revision chain, ensuring a comprehensive understanding of its journey and transformations. It's designed to empower users with transparency and traceability, crucial for trust in Human-AI orchestration.

Responses

Response samples

Content type
application/json

Retrieve artifact details for Acme Corp's invoice processing system.

{
  • "artifact_id": "artifact-12345",
  • "name": "Invoice Processing System",
  • "description": "Handles the processing of invoices for Acme Corp.",
  • "created_at": "2023-10-01T12:00:00Z",
  • "provenance": [
    ],
  • "revision_chain": [
    ]
}

Export Artifacts with Provenance Data

Retrieve a detailed export of your organization's artifacts, complete with provenance. This endpoint empowers organizations to track the lineage and history of each artifact, ensuring transparency and accountability in task management. Ideal for auditing and operational insights.

Responses

Response samples

Content type
application/json

A JSON export of artifacts with provenance for the organization.

{
  • "org_did": "did:human:acme-org-123",
  • "artifacts": [
    ],
  • "exported_at": "2023-10-05T15:00:00Z",
  • "has_more": false,
  • "next_cursor": null
}

Retrieve provenance for artifact

Uncover the journey of an artifact within the HUMAN ecosystem. This endpoint allows organizations to trace the provenance of their artifacts, providing an insightful look into its history and transformations, ensuring transparency and fraud prevention.

Responses

Response samples

Content type
application/json

An example response showing the provenance of an artifact.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Revise existing artifact for enhancement

Revise an existing artifact to incorporate updates or corrections, ensuring the artifact evolves with your organization's needs. This endpoint facilitates the continuous improvement of your digital assets, promoting agility and precision in Human-AI orchestration.

Request Body schema: application/json
required
title
string

Optional new title for the artifact.

metadata
object

Optional metadata specific to the artifact's kind.

body
object

The content of the artifact, constrained by size.

media_type
string

The media type of the artifact content.

summary
string

A brief summary of the changes made during the revision.

Responses

Request samples

Content type
application/json

An example of revising an artifact related to invoice processing in the 'acme' organization.

{
  • "title": "Updated Invoice Processing",
  • "metadata": {
    },
  • "body": {
    },
  • "media_type": "application/json",
  • "summary": "Improved step-by-step guide for invoice processing."
}

Response samples

Content type
application/json
null

Retrieve Agent Artifacts with Provenance

Uncover the wealth of artifacts associated with a specific agent within an organization, tracing the lineage and evolution of each piece. This endpoint helps ensure transparency and trust in AI-driven tasks by presenting a detailed history of artifact creation and modification.

Responses

Response samples

Content type
application/json
{
  • "agent_id": "agent-1234",
  • "org_did": "did:human:acme",
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Artifact

Retrieve artifact explanation bundle

Dive deep into the workings of your AI artifact with this endpoint. It unveils the intricate policies and learning adaptations that shape your artifact's lifecycle, providing insights into the AI decisions and their provenance. This is where AI transparency meets operational intelligence.

Responses

Response samples

Content type
application/json

An insightful explanation of an artifact belonging to Acme Corp, revealing its state and the decisions influencing it.

{
  • "summary": "Artifact 12345 is in state active. Effective HumanOS org policy (P8) is applied as hos_pol:acme:2023-10-05T14:48:00Z.",
  • "factors": [
    ],
  • "related_work_refs": [
    ],
  • "confidence": {
    },
  • "learning": {
    }
}

Feedback

Submit Feedback Event for HumanOS

This endpoint lets organizations send feedback events to HumanOS, enabling a collaborative environment between human efforts and AI. By doing so, it ensures that the AI is continuously learning and evolving based on real-world inputs and organizational policies.

Request Body schema: application/json
required
scope
string

The scope of the feedback event, defaults to 'user'.

payload_type
required
string

The type of feedback event being submitted. Must be a known HumanOS v1 feedback event type.

passport_did
string

The Passport DID associated with the feedback event.

target_kind
string

The kind of target entity for the feedback.

target_id
string

The identifier of the target entity.

payload
object

Additional data related to the feedback event.

Responses

Request samples

Content type
application/json

A simple example of submitting a feedback event with mandatory fields.

{
  • "scope": "team",
  • "payload_type": "task_completion",
  • "passport_did": "did:human:abcd1234",
  • "target_kind": "task",
  • "target_id": "task-5678",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "feedback_id": "evt-9012",
  • "org_did": "did:org:acme123",
  • "scope": "team",
  • "payload_type": "task_completion",
  • "created_at": "2023-10-01T12:15:00Z"
}

Retrieve feedback events for an organization

Explore the trail of feedback events that have shaped the human-AI collaboration within your organization. This endpoint unravels the narrative of how feedback flows through the HUMAN ecosystem, tracking its origins and destinations.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Submit feedback for a signal event

In the intricate dance of human and AI collaboration, feedback serves as the guiding hand. This endpoint allows organizations to provide nuanced feedback on specific signals, ensuring that AI-driven processes remain aligned with human intent. Whether acknowledging high impact or flagging misclassifications, this feedback loop enhances the orchestration of tasks.

Request Body schema: application/json
required
kind
required
string
Enum: "flag" "dismiss" "watch" "not_useful" "misclassified" "high_impact" "route_differently"

The type of feedback being provided

note
string

Optional note elaborating on the feedback, up to 4000 characters

scope
string

The scope of feedback, defaulting to 'org' if not specified

Responses

Request samples

Content type
application/json

This example illustrates submitting feedback when a signal is misclassified.

{
  • "kind": "misclassified",
  • "note": "The signal was incorrectly categorized under 'urgent'.",
  • "scope": "project"
}

Response samples

Content type
application/json
{
  • "feedback_event_id": "fdbk12345",
  • "org_did": "did:example:acme",
  • "signal_id": "sig7890",
  • "kind": "misclassified",
  • "created_at": "2023-10-15T14:23:00Z"
}

Transparency

Retrieve provenance for artifact

Uncover the journey of an artifact within the HUMAN ecosystem. This endpoint allows organizations to trace the provenance of their artifacts, providing an insightful look into its history and transformations, ensuring transparency and fraud prevention.

Responses

Response samples

Content type
application/json

An example response showing the provenance of an artifact.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Artifact Management

Record artifact provenance

As digital artifacts evolve, tracking their history is paramount. This endpoint allows organizations to chronicle the provenance of an artifact, ensuring transparency and accountability in its lifecycle. By embedding a cryptographic signature, it guarantees authenticity and trustworthiness.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Provenance Tracking

Record artifact provenance

As digital artifacts evolve, tracking their history is paramount. This endpoint allows organizations to chronicle the provenance of an artifact, ensuring transparency and accountability in its lifecycle. By embedding a cryptographic signature, it guarantees authenticity and trustworthiness.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

ControlPanel

Retrieve organization's CP extensions

Explore the vibrant ecosystem of Control Panel extensions tailored for your organization. This endpoint empowers admins by offering a detailed list of extensions, showcasing each tool's capabilities and potential to enhance your organization's operational efficiency.

Responses

Response samples

Content type
application/json
{
  • "org_did": "did:example:123456789",
  • "extensions": [
    ]
}

Agent

Retrieve daily agent performance metrics

Dive into the world of agent performance with this endpoint, which reveals the intricate dance of invocations, tokens, and operation durations over time. It's not just data — it's the heartbeat of your AI agents, empowering you to optimize and understand their daily rhythm.

Responses

Response samples

Content type
application/json

Example of retrieving invocation metrics for an agent over a default window of 30 days.

{
  • "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  • "metric": "invocations",
  • "window_days": 30,
  • "series": [
    ],
  • "placeholder": false
}

Metrics

Retrieve daily agent performance metrics

Dive into the world of agent performance with this endpoint, which reveals the intricate dance of invocations, tokens, and operation durations over time. It's not just data — it's the heartbeat of your AI agents, empowering you to optimize and understand their daily rhythm.

Responses

Response samples

Content type
application/json

Example of retrieving invocation metrics for an agent over a default window of 30 days.

{
  • "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  • "metric": "invocations",
  • "window_days": 30,
  • "series": [
    ],
  • "placeholder": false
}

Retrieve Action Receipt Coverage Metric

Gauge the fidelity of human-AI interactions within your organization by examining the proportion of completed tasks that include an ActionReceipt. This metric helps ensure compliance with the ActionReceipt contract, targeting a coverage ratio of 90% or higher.

Responses

Response samples

Content type
application/json
{
  • "org_did": "did:example:123456789abcdefghi",
  • "window_days": 7,
  • "completed_invocations_sampled": 150,
  • "with_action_receipt": 135,
  • "receipt_coverage_ratio": 0.9,
  • "note": "Sampled from idempotency_keys (cached human.call responses). Target ≥ 0.9 per ActionReceipt contract."
}

Retrieve summary of incident metrics

Dive into the heart of your organization’s incident handling with this endpoint. It provides a comprehensive summary of incident metrics, filtered by severity and status, empowering you to understand patterns and improve response strategies. This endpoint exists to ensure that organizations can proactively manage and mitigate incidents before they escalate.

Responses

Response samples

Content type
application/json

Acme Corp’s incident metrics summary shows a balanced view of incidents by severity and status.

{
  • "org_did": "did:example:acme",
  • "total_count": 42,
  • "by_severity": {
    },
  • "by_status": {
    },
  • "breakdown": [
    ]
}

AgentManagement

Retrieve Effective Agent Policy

Unlock the power of HumanOS by accessing the effective policy for a specified agent. This endpoint helps organizations monitor and enforce skill progress gates, ensuring every agent adheres to the orchestrated protocol.

Responses

Response samples

Content type
application/json
{
  • "agent_id": "agent123",
  • "org_did": "did:human:org:acme",
  • "policy_json": {
    }
}

Execution History

Retrieve agent execution history

Delve into the rich tapestry of an agent's past activities by retrieving its execution history. This endpoint allows you to explore how agents have been invoked, their performance over time, and any associated costs or errors, providing transparency and accountability.

Responses

Response samples

Content type
application/json

A list of past executions for agent 'acme:invoice-processor'.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "execution_id"
}

Financial

Retrieve agent cost breakdown

Explore the detailed cost analysis of an agent over a specified period. This endpoint unveils the financial footprint of AI interactions, empowering organizations to optimize resource allocation and manage budgets effectively.

Responses

Response samples

Content type
application/json

Cost breakdown example for Acme's AI Agent over a 7-day period.

{
  • "total_cost_usd": 349.5,
  • "period": "7d",
  • "by_day": [
    ],
  • "top_executions": [
    ]
}

Versions

Retrieve all deployed agent versions

Explore the evolution of your AI agents with this endpoint, which lists all the deployed versions. This helps organizations track changes over time, ensuring the right skills are deployed at the right moments, ultimately enhancing AI strategy and effectiveness.

Responses

Response samples

Content type
application/json

List of versions for the agent 'acme:123'.

{
  • "data": [
    ],
  • "pagination": {
    }
}

Logs

Stream real-time logs for agents

Dive into the pulsating life of an agent with real-time log streaming. Though this feature is a placeholder for now, it promises to reveal the intricate dance of actions and reactions in your AI operations once fully implemented. Keep your eyes peeled for Phase 6e when this becomes a reality.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/not-found",
  • "title": "Agent Not Found",
  • "status": 404,
  • "detail": "No agent found with DID or org_agent_id matching 'agent123'. Verify the agent ID and try again."
}

Companion Modules

Retrieve organization's active companion modules

Unveil the ensemble of companion modules that your organization actively leverages to enhance its capabilities. This endpoint empowers you with insights into each module's specifics, facilitating strategic orchestration and informed decision-making.

Responses

Response samples

Content type
application/json

An example response showing Acme Corp's active companion modules.

{
  • "org_did": "did:human:acme",
  • "companion_modules": [
    ]
}

Workforce Modules

Retrieve Active Workforce Modules

Unveil the capabilities of your organization by retrieving active workforce modules. This endpoint empowers you to understand and manage the skills and tools available within your organization, ensuring optimal orchestration of human and AI efforts.

Responses

Response samples

Content type
application/json

A list of active workforce modules for Acme Corp, showcasing their installed capabilities.

{
  • "org_did": "did:example:123456",
  • "modules": [
    ]
}

Platform

Discover HUMAN platform capabilities

Uncover the powerful orchestration capabilities of the HUMAN Protocol. This endpoint offers a glimpse into the platform's operational status and available paths, guiding users through a seamless integration into the future of Human-AI collaboration.

Responses

Response samples

Content type
application/json

An example of the HUMAN Protocol platform in full operational status.

{
  • "platform": "HUMΛN Orchestration Protocol",
  • "version": "v1",
  • "status": "operational",
  • "authentication": {
    },
  • "api_reference": "/v1/openapi.json",
  • "capabilities_catalog": "/v1/system-capabilities",
  • "knowledge": "https://console.haio.run/ai/llms.txt",
  • "endpoints": {
    },
  • "links": {}
}

Tool Discovery

Discover and propose agent tool schemas

Unveil the potential of your organization by discovering agent tools tailored to your specific capabilities. This endpoint serves as a bridge between your organizational needs and the world of Human-AI orchestration, suggesting agent tools that align with your capabilities, workforce, and marketplace opportunities.

Request Body schema: application/json
required
org_id
required
string

The organization's unique identifier

capabilities
Array of strings

List of capability URIs to match against agent tools

agent_ids
Array of strings

Specific agent IDs to filter results

include_workforce
boolean

Include workforce in the search results

include_marketplace
boolean

Include marketplace suggestions in the results

Responses

Request samples

Content type
application/json

Showcases a request from Acme Corp to find tools matching their capabilities

{
  • "org_id": "acme-corp",
  • "capabilities": [
    ],
  • "agent_ids": [ ],
  • "include_workforce": true,
  • "include_marketplace": true
}

Response samples

Content type
application/json

The response for a successful tool discovery request by Acme Corp

{
  • "tools": [
    ],
  • "workforce_workers": [
    ],
  • "marketplace_suggestions": [ ],
  • "capability_gaps": [ ],
  • "org_id": "acme-corp",
  • "tools_count": 1,
  • "workers_count": 1,
  • "suggestions_count": 0
}

Automation

Trigger a workflow manually

Spark the lifeline of automation by manually triggering a workflow. This endpoint initiates a new Directed Acyclic Graph (DAG) root node and sends a beacon, the workflow.manual-trigger event, for Inngest to capture and act upon. It's designed for those moments when you need to intervene and start a process outside the regular flow, providing flexibility and control in orchestrating complex operations.

Request Body schema: application/json
required
context
object

Additional data to pass along with the workflow trigger

Responses

Request samples

Content type
application/json

Triggering a workflow with minimal context

{
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "workflow_id": "wf12345",
  • "run_id": "wrun67890",
  • "status": "triggered",
  • "triggered_at": "2023-10-11T14:32:08Z"
}

Extensions

Install an Extension for an Organization

Empower your organization by seamlessly integrating new capabilities through extensible modules. This endpoint is the gateway to enhancing your operational landscape by installing extensions that align with your strategic goals.

Request Body schema: application/json
required
extensionId
required
string

Unique identifier of the extension to be installed.

config
object

Optional configuration settings for the extension.

Responses

Request samples

Content type
application/json

Installing the 'invoice-processor' extension with default settings.

{
  • "extensionId": "invoice-processor",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "inst_1234567890abcdef",
  • "entity_id": "org_acme_corp",
  • "extension_id": "invoice-processor",
  • "permissions": [ ],
  • "config": {
    },
  • "status": "active",
  • "triggers": null,
  • "installed_at": "2023-10-05T14:48:00Z",
  • "updated_at": "2023-10-05T14:48:00Z"
}

Retrieve installed extensions for organization

Unlock the potential of your organization by exploring the array of extensions currently installed. This endpoint offers a curated view into your toolkit, empowering you to harness the full spectrum of capabilities tailored to your needs. By understanding what's active, you can strategize your next innovations and streamline operations.

Responses

Response samples

Content type
application/json

Shows a typical response with two installed extensions.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": false
}

Remove an installed extension securely

Uninstalling an extension is crucial when you no longer need its capabilities or when it's outdated. This endpoint ensures safe removal by verifying user permissions, maintaining system integrity through transactional deletions, and updating provenance records. Such careful measures protect your organization's data and AI processes.

Responses

Response samples

Content type
application/json

An extension is removed successfully from the system.

null

Invoke an extension's capability for action

Unlock the potential of your organization's installed extensions by invoking specific capabilities. This endpoint is the gateway to extending functionality, allowing you to orchestrate tasks and actions with precision and control. It exists to seamlessly integrate and activate the diverse capabilities within your distributed AI systems.

Request Body schema: application/json
required
capability
required
string

The capability to be invoked, identified by a URI

action
string

The action to perform using the capability

params
object

Parameters required for the action

Responses

Request samples

Content type
application/json

Invoke the 'processInvoice' capability to automate invoice handling for the 'acme' organization.

{
  • "capability": "capability://acme/invoice/process",
  • "action": "process",
  • "params": {
    }
}

Response samples

Content type
application/json
null

Process incoming webhooks for extensions

This endpoint orchestrates the reception of webhooks from external services for specific extensions, ensuring seamless integration and task automation. It empowers developers to extend the HUMAN platform by acknowledging incoming data from third-party sources, facilitating a real-time, responsive ecosystem.

Request Body schema: application/json
required
event
required
string

The type of event triggering the webhook

object

The event-specific data payload

Responses

Request samples

Content type
application/json

A webhook event triggered by an external service

{
  • "event": "invoice.processed",
  • "data": {
    }
}

Response samples

Content type
application/json
null

Retrieve Available Extensions for Navigation

Discover the universe of extensions tailored to your organization's needs, filtered by navigation scope. This endpoint opens the door to a curated selection of tools, enhancing your organization's capabilities with precision.

Responses

Response samples

Content type
application/json

A user from the 'acme' organization retrieves extensions related to the 'companion_panel' navigation scope.

{
  • "extensions": [
    ]
}

Executions

Retrieve Execution Records for Organization

Dive into the orchestration of AI and human tasks with detailed execution records. This endpoint empowers organizations by retrieving the history of task executions, allowing for insightful analysis and optimization of processes. By filtering through status and surface, organizations can pinpoint specific operations and evaluate their effectiveness.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Bundles

Preview Marketplace Bundle Installation

Embark on a journey to seamlessly preview the installation of marketplace bundles. This endpoint offers a glimpse into the future, enabling organizations to assess the impact and compatibility of installing a new bundle before committing to it, ensuring smooth transitions and maintaining operational harmony.

Request Body schema: application/json
required
asset_id
required
string

The unique identifier for the asset bundle.

org_did
required
string

The decentralized identifier for the organization.

preset
string
Enum: "safe" "autopilot" "custom"

The installation preset to use, offering various levels of automation and safety.

Responses

Request samples

Content type
application/json

Previewing the installation of a bundle with standard safety preset in the ACME organization.

{
  • "asset_id": "bundle12345",
  • "org_did": "did:human:acme-org",
  • "preset": "safe"
}

Response samples

Content type
application/json
{
  • "preview": {
    },
  • "policy_compatibility": {
    }
}

Compensate bundle installation rollback

When an AI bundle installation encounters an unforeseen rollback or partial failure, the compensate endpoint restores balance. By invoking this endpoint, operators ensure the orchestration environment remains consistent, resolving issues without manual intervention.

Request Body schema: application/json
required
bundle_installation_id
required
string

Unique identifier of the bundle installation

org_did
required
string

Decentralized Identifier (DID) of the organization

Responses

Request samples

Content type
application/json

Request to compensate a rollback for 'acme' organization

{
  • "bundle_installation_id": "abc123xyz",
  • "org_did": "did:human:acme-456"
}

Response samples

Content type
application/json
{
  • "message": "Compensation completed successfully for bundle installation abc123xyz"
}

KnowledgeBase

Retrieve Knowledge Base Documents

This endpoint unveils the curated tapestry of documents within your knowledge base, meticulously orchestrated to balance access with governance. Imagine delving into a library where every book is tailored to your unique Passport — this is your gateway.

Responses

Response samples

Content type
application/json

A list of documents accessible to the user with 'Internal' classification.

{
  • "documents": [
    ]
}

Synchronize Knowledge Base Index

Refresh your knowledge base index with a single request. This endpoint ensures that your knowledge base is current and ready to provide the most accurate information when called upon. Ideal for organizations seeking to maintain an up-to-date repository of knowledge.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json

A request to synchronize the knowledge base index from an authorized user.

{
  • "delegation": {
    }
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "synced_at": "2023-10-05T14:48:00.000Z",
  • "message": "KB index refreshed on next request (filesystem-backed)"
}

Delegation-scoped KB search with access control

Embark on a quest through the HUMAN knowledge base, where access is determined by the cryptographic credentials you hold. This endpoint allows users to conduct a full-text search, unveiling documents their delegation token permits, ensuring both security and precision in knowledge retrieval.

query Parameters
q
required
string non-empty
Example: q=capability graph design

Search query string matched against KB document titles, summaries, and content.

limit
integer [ 1 .. 50 ]
Default: 10
Example: limit=20

Maximum number of results to return. Capped at 50 regardless of the value supplied.

classification
string
Enum: "ExternalPartner" "Public"

Override the access ceiling for ExternalPartner-scoped tokens. Tokens that already hold kb:read:internal scope receive Internal access and this parameter is ignored.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 1,
  • "query": "AI ethics",
  • "classification_ceiling": "Public"
}

Retrieve Knowledge Base Document by ID

Dive into the rich tapestry of knowledge stored within the HUMAN platform. This endpoint allows you to fetch a specific Knowledge Base document, unlocking the power of collective insights. Whether you're an AI seeking guidance or a human exploring new realms, retrieving this document can be your compass.

Responses

Response samples

Content type
application/json

The document about AI safety protocols.

{
  • "id": "kb-123",
  • "title": "Understanding AI Safety",
  • "path": "/docs/ai-safety",
  • "classification": "Public",
  • "governance_tier": "Tier 1",
  • "summary": "An overview of protocols ensuring safe AI deployment.",
  • "content": "The content delves into various AI safety protocols...",
  • "last_updated": "2023-10-12T14:22:00Z"
}

Retrieve accessible knowledge base documents

Unleash the full potential of your organization's knowledge by accessing documents curated to your session's security clearance. This endpoint provides a tailored list of knowledge base entries, ensuring that every piece of information you view aligns with your classification tier, be it public or internal. Harnessing the HUMAN protocol, it empowers MCP resource listings with precision and safety.

Responses

Response samples

Content type
application/json

Shows retrieval of internal documents for Acme Corp.

{
  • "items": [
    ],
  • "total": 2,
  • "classification_ceiling": "Internal"
}

Speech

Transcribe audio into text with AI

Effortlessly convert spoken words into written text through our advanced AI-driven transcription service. Perfect for capturing meeting notes, interviews, or any spoken content, ensuring every word is accounted for with precision and efficiency.

Request Body schema: application/json
required
audio
required
string <binary>

Audio file to be transcribed, in WebM format

language
string

Optional language code for transcription

Responses

Request samples

Content type
application/json

Transcribe a WebM audio file in English

{
  • "audio": "<binary audio data>",
  • "language": "en"
}

Response samples

Content type
application/json

Transcription of a meeting recording

{
  • "text": "Welcome to the quarterly financial meeting...",
  • "language": "en",
  • "duration_ms": 45000,
  • "cost": {
    }
}

Synthesize text into spoken audio

Transform written text into lifelike spoken audio, bridging communication gaps effortlessly. This endpoint empowers applications to produce voice output, enhancing accessibility and user interaction by converting text into speech.

Request Body schema: application/json
required
text
required
string

The text content to be synthesized into speech.

voice_id
string

Identifier for the voice to use. Defaults to 'alloy'.

format
string
Enum: "mp3" "wav"

Audio format for the output. Defaults to 'mp3'.

Responses

Request samples

Content type
application/json

Convert a simple text string into speech using default settings.

{
  • "text": "Hello, world!",
  • "voice_id": "alloy",
  • "format": "mp3"
}

Response samples

Content type
application/json

MP3 audio of 'Hello, world!'

"<binary audio data>"

Transcription

Transcribe audio into text with AI

Effortlessly convert spoken words into written text through our advanced AI-driven transcription service. Perfect for capturing meeting notes, interviews, or any spoken content, ensuring every word is accounted for with precision and efficiency.

Request Body schema: application/json
required
audio
required
string <binary>

Audio file to be transcribed, in WebM format

language
string

Optional language code for transcription

Responses

Request samples

Content type
application/json

Transcribe a WebM audio file in English

{
  • "audio": "<binary audio data>",
  • "language": "en"
}

Response samples

Content type
application/json

Transcription of a meeting recording

{
  • "text": "Welcome to the quarterly financial meeting...",
  • "language": "en",
  • "duration_ms": 45000,
  • "cost": {
    }
}

Synthesis

Synthesize text into spoken audio

Transform written text into lifelike spoken audio, bridging communication gaps effortlessly. This endpoint empowers applications to produce voice output, enhancing accessibility and user interaction by converting text into speech.

Request Body schema: application/json
required
text
required
string

The text content to be synthesized into speech.

voice_id
string

Identifier for the voice to use. Defaults to 'alloy'.

format
string
Enum: "mp3" "wav"

Audio format for the output. Defaults to 'mp3'.

Responses

Request samples

Content type
application/json

Convert a simple text string into speech using default settings.

{
  • "text": "Hello, world!",
  • "voice_id": "alloy",
  • "format": "mp3"
}

Response samples

Content type
application/json

MP3 audio of 'Hello, world!'

"<binary audio data>"

Data Integration

Register a new signal source

Integrate a new source of data into your organization's HUMAN protocol. This endpoint allows you to specify a data source that will be tracked and analyzed for insights, helping you leverage diverse information streams efficiently.

Request Body schema: application/json
required
name
required
string

The human-readable name of the signal source.

kind
required
string
Enum: "website" "api" "rss" "github" "social" "upload" "custom"

The category defining the type of signal source.

object

Optional configuration settings specific to the signal source.

status
string
Default: "active"
Enum: "active" "inactive"

The initial status of the signal source.

Responses

Request samples

Content type
application/json

Create a signal source with minimal required fields.

{
  • "name": "Acme Corp GitHub",
  • "kind": "github",
  • "config": {
    },
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "source_id": "sig_src_12345",
  • "org_did": "did:example:acme",
  • "name": "Acme Corp GitHub",
  • "kind": "github",
  • "config": {
    },
  • "status": "active",
  • "last_scanned_at": null,
  • "created_at": "2023-10-25T14:48:00Z",
  • "updated_at": "2023-10-25T14:48:00Z"
}

Signal Management

Register a new signal source

Integrate a new source of data into your organization's HUMAN protocol. This endpoint allows you to specify a data source that will be tracked and analyzed for insights, helping you leverage diverse information streams efficiently.

Request Body schema: application/json
required
name
required
string

The human-readable name of the signal source.

kind
required
string
Enum: "website" "api" "rss" "github" "social" "upload" "custom"

The category defining the type of signal source.

object

Optional configuration settings specific to the signal source.

status
string
Default: "active"
Enum: "active" "inactive"

The initial status of the signal source.

Responses

Request samples

Content type
application/json

Create a signal source with minimal required fields.

{
  • "name": "Acme Corp GitHub",
  • "kind": "github",
  • "config": {
    },
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "source_id": "sig_src_12345",
  • "org_did": "did:example:acme",
  • "name": "Acme Corp GitHub",
  • "kind": "github",
  • "config": {
    },
  • "status": "active",
  • "last_scanned_at": null,
  • "created_at": "2023-10-25T14:48:00Z",
  • "updated_at": "2023-10-25T14:48:00Z"
}

Update Signal Source Details

Modify the attributes of an existing signal source to keep your data orchestration precise and up-to-date. With HUMAN's capability graph, track and manage your signal sources efficiently, ensuring seamless integration in your AI workflows.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Remove a signal source by ID

In the orchestration of human and AI tasks, sometimes certain data sources become obsolete or redundant. This endpoint empowers organizations to manage their signal sources dynamically, ensuring that only relevant data feeds into their Human-AI orchestration processes.

Responses

Response samples

Content type
application/problem+json

The source ID format was incorrect.

{}

Route and Update Signal Verdict

This endpoint empowers organizations to dynamically update the verdict of a signal and adjust its routing metadata. It serves as a crucial touchpoint for ensuring signals are processed accurately and efficiently within the HUMAN Protocol, reflecting real-time decision-making and task management.

Request Body schema: application/json
required
verdict
string
Enum: "pending" "approved" "suppressed" "routed"

The new verdict for the signal.

route_action
string

Action taken for routing the signal.

metadata_patch
object

Partial metadata update for the signal.

Responses

Request samples

Content type
application/json

Example showing how to approve a signal and set a route action.

{
  • "verdict": "approved",
  • "route_action": "escalate",
  • "metadata_patch": {
    }
}

Response samples

Content type
application/json
null

Signals

Retrieve paginated signal sources

Delve into the intricate network of signal sources within your organization. This endpoint is your gateway to exploring the multitude of data origins, empowering you with the oversight of source management and performance at scale. Discover the orchestration behind signal acquisition and make informed decisions based on real-time data.

Responses

Response samples

Content type
application/json

An example of signal sources for the 'acme' organization, illustrating pagination and source attributes.

{
  • "data": [
    ],
  • "hasMore": false,
  • "limit": 10,
  • "cursorFields": [
    ]
}

Retrieve details of a signal source

Dive into the depths of your organization's data with this endpoint, which uncovers the specific characteristics of a signal source within your organization. By securely querying this resource, you gain insights into the configurations and statuses that define your data streams, empowering data-driven decisions.

Responses

Response samples

Content type
application/json

Details of a signal source used by Acme organization for data streaming.

{
  • "source_id": "source_123",
  • "org_did": "did:example:acme",
  • "name": "Acme Data Stream",
  • "kind": "stream",
  • "config": {},
  • "status": "active",
  • "last_scanned_at": "2023-09-15T13:45:30Z",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-09-14T12:34:56Z"
}

Create a new watchlist for signals

In the dynamic realm of signal monitoring, orchestrate your focus by creating watchlists tailored to organizational needs. This endpoint empowers users to define and manage collections of signals, ensuring strategic oversight and prompt action.

Request Body schema: application/json
required
name
required
string

A unique name for the watchlist.

description
string

Optional description of the watchlist.

owner_ref
string

Reference to the owner, defaults to requesting user's delegation ID.

status
string
Default: "active"
Enum: "active" "inactive" "archived"

The operational status of the watchlist.

object

Configuration settings for the watchlist.

Responses

Request samples

Content type
application/json

This example demonstrates creating a simple active watchlist with default owner.

{
  • "name": "High Priority Alerts",
  • "description": "Monitor high priority signals for immediate action.",
  • "status": "active",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "watchlist_id": "sig_wl_123456",
  • "org_did": "did:example:acme",
  • "name": "High Priority Alerts",
  • "description": "Monitor high priority signals for immediate action.",
  • "owner_ref": "agent_007",
  • "status": "active",
  • "config": {
    },
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-01T12:00:00Z"
}

Retrieve organization's watchlists

Explore the curated watchlists within your organization, offering insights into tracked signals and configurations. This endpoint empowers organizations to efficiently manage and review their signal monitoring setups, ensuring timely and precise oversight.

Responses

Response samples

Content type
application/json

Retrieve Acme Corp's active watchlists for monitoring signals.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Retrieve details of a specific watchlist

This endpoint allows organizations to retrieve comprehensive details of a specific watchlist they own or manage. It empowers users to access critical information such as configuration and status, supporting data-driven decision-making and proactive monitoring.

Responses

Response samples

Content type
application/json

Details of the 'Acme Corp Threat Watchlist'.

{
  • "watchlist_id": "wl-12345",
  • "org_did": "did:org:acme",
  • "name": "Threat Watchlist",
  • "description": "Monitors potential threats to Acme Corp.",
  • "owner_ref": "agent:john.doe",
  • "status": "active",
  • "config": {
    },
  • "created_at": "2023-09-15T08:30:00Z",
  • "updated_at": "2023-10-01T12:00:00Z",
  • "source_ids": [
    ]
}

Update an existing watchlist entry

In the ever-evolving world of AI-human collaboration, keeping track of signals is crucial. This endpoint allows you to update the details of a watchlist, ensuring your team stays informed and agile. Whether it's a name change or a status update, this operation ensures your watchlists reflect the latest intelligence.

Request Body schema: application/json
required
name
string

The new name for the watchlist.

description
string

A brief description of the watchlist.

status
string
Enum: "active" "paused" "archived"

The operational status of the watchlist.

config
object

Configuration settings for the watchlist.

Responses

Request samples

Content type
application/json

This example demonstrates updating the name and status of a watchlist.

{
  • "name": "High Priority Signals",
  • "status": "active"
}

Response samples

Content type
application/json

Key signals for top-tier clients.

null

Remove a watchlist from signals

Effortlessly manage your signal monitoring by removing watchlists no longer needed, ensuring your human-AI orchestration remains efficient and focused. This endpoint allows organizations to delete outdated or irrelevant watchlists, keeping their signal tracking streamlined.

Responses

Response samples

Content type
application/json

Confirmation of watchlist removal.

null

Update sources in a watchlist

This endpoint redefines the sources linked to a specific watchlist, allowing organizations to dynamically adjust their surveillance scope. By managing these sources, businesses can precisely tailor their signal monitoring to stay ahead in their domain.

Request Body schema: application/json
required
source_ids
required
Array of strings

A list of source IDs that the watchlist should monitor.

Responses

Request samples

Content type
application/json

This example updates a watchlist with multiple sources.

{
  • "source_ids": [
    ]
}

Response samples

Content type
application/json

Monitoring key market indicators.

null

Retrieve curated signals feed

Dive into the dynamic world of AI and human collaboration by accessing a curated feed of signals. This endpoint empowers organizations to filter and analyze signals based on watchlists, event types, verdicts, and confidence levels. It exists to provide transparency and actionable insights, ensuring that organizations can make informed decisions swiftly.

Responses

Response samples

Content type
application/json

An example response showing a list of signals for an organization with pagination.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Create a new signal feed entry

The POST /v1/signals/feed endpoint allows organizations to manually ingest new signals into the HUMAN platform. By crafting a feed entry, organizations can showcase their capabilities, demonstrate prowess, and ensure their skills are recognized in the HUMAN ecosystem.

Request Body schema: application/json
required
title
required
string

Title of the signal.

description
required
string

Detailed description of the signal.

timestamp
required
string <date-time>

The time at which the signal was generated.

tags
Array of strings

Tags categorizing the signal.

Responses

Request samples

Content type
application/json

This example demonstrates how an organization might submit a signal for an AI capability demonstration.

{
  • "title": "AI Capability Demonstration",
  • "description": "A demonstration of AI capabilities integrating HUMAN Passport and Capability Graph.",
  • "timestamp": "2023-09-15T14:30:00Z",
  • "tags": [
    ]
}

Response samples

Content type
application/json
null

Retrieve signal details from feed

Delve into the heartbeat of your organization by fetching detailed insights from the signal feed. This endpoint allows you to track pivotal events and analyze their importance for strategic decision-making, ensuring every action is informed by data-driven intelligence.

Responses

Response samples

Content type
application/json
{
  • "signal_id": "12345",
  • "org_did": "did:example:org123",
  • "source_id": "source789",
  • "watchlist_id": "watchlist456",
  • "event_type": "anomaly_detected",
  • "entity_ref": "entity:acme:invoice:67890",
  • "title": "Unexpected Invoice Surge",
  • "summary": "A sudden increase in invoice submissions was detected.",
  • "confidence": 0.92,
  • "relevance_score": 0.85,
  • "verdict": "review_required",
  • "artifact_ids": [
    ],
  • "metadata": { },
  • "occurred_at": "2023-10-15T14:48:00Z",
  • "created_at": "2023-10-15T15:00:00Z"
}

Submit feedback for a signal event

In the intricate dance of human and AI collaboration, feedback serves as the guiding hand. This endpoint allows organizations to provide nuanced feedback on specific signals, ensuring that AI-driven processes remain aligned with human intent. Whether acknowledging high impact or flagging misclassifications, this feedback loop enhances the orchestration of tasks.

Request Body schema: application/json
required
kind
required
string
Enum: "flag" "dismiss" "watch" "not_useful" "misclassified" "high_impact" "route_differently"

The type of feedback being provided

note
string

Optional note elaborating on the feedback, up to 4000 characters

scope
string

The scope of feedback, defaulting to 'org' if not specified

Responses

Request samples

Content type
application/json

This example illustrates submitting feedback when a signal is misclassified.

{
  • "kind": "misclassified",
  • "note": "The signal was incorrectly categorized under 'urgent'.",
  • "scope": "project"
}

Response samples

Content type
application/json
{
  • "feedback_event_id": "fdbk12345",
  • "org_did": "did:example:acme",
  • "signal_id": "sig7890",
  • "kind": "misclassified",
  • "created_at": "2023-10-15T14:23:00Z"
}

Sources

Retrieve paginated signal sources

Delve into the intricate network of signal sources within your organization. This endpoint is your gateway to exploring the multitude of data origins, empowering you with the oversight of source management and performance at scale. Discover the orchestration behind signal acquisition and make informed decisions based on real-time data.

Responses

Response samples

Content type
application/json

An example of signal sources for the 'acme' organization, illustrating pagination and source attributes.

{
  • "data": [
    ],
  • "hasMore": false,
  • "limit": 10,
  • "cursorFields": [
    ]
}

DataManagement

Retrieve details of a signal source

Dive into the depths of your organization's data with this endpoint, which uncovers the specific characteristics of a signal source within your organization. By securely querying this resource, you gain insights into the configurations and statuses that define your data streams, empowering data-driven decisions.

Responses

Response samples

Content type
application/json

Details of a signal source used by Acme organization for data streaming.

{
  • "source_id": "source_123",
  • "org_did": "did:example:acme",
  • "name": "Acme Data Stream",
  • "kind": "stream",
  • "config": {},
  • "status": "active",
  • "last_scanned_at": "2023-09-15T13:45:30Z",
  • "created_at": "2023-01-01T00:00:00Z",
  • "updated_at": "2023-09-14T12:34:56Z"
}

Data Orchestration

Update Signal Source Details

Modify the attributes of an existing signal source to keep your data orchestration precise and up-to-date. With HUMAN's capability graph, track and manage your signal sources efficiently, ensuring seamless integration in your AI workflows.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Data Sources

Remove a signal source by ID

In the orchestration of human and AI tasks, sometimes certain data sources become obsolete or redundant. This endpoint empowers organizations to manage their signal sources dynamically, ensuring that only relevant data feeds into their Human-AI orchestration processes.

Responses

Response samples

Content type
application/problem+json

The source ID format was incorrect.

{}

Watchlists

Create a new watchlist for signals

In the dynamic realm of signal monitoring, orchestrate your focus by creating watchlists tailored to organizational needs. This endpoint empowers users to define and manage collections of signals, ensuring strategic oversight and prompt action.

Request Body schema: application/json
required
name
required
string

A unique name for the watchlist.

description
string

Optional description of the watchlist.

owner_ref
string

Reference to the owner, defaults to requesting user's delegation ID.

status
string
Default: "active"
Enum: "active" "inactive" "archived"

The operational status of the watchlist.

object

Configuration settings for the watchlist.

Responses

Request samples

Content type
application/json

This example demonstrates creating a simple active watchlist with default owner.

{
  • "name": "High Priority Alerts",
  • "description": "Monitor high priority signals for immediate action.",
  • "status": "active",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "watchlist_id": "sig_wl_123456",
  • "org_did": "did:example:acme",
  • "name": "High Priority Alerts",
  • "description": "Monitor high priority signals for immediate action.",
  • "owner_ref": "agent_007",
  • "status": "active",
  • "config": {
    },
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-01T12:00:00Z"
}

Retrieve organization's watchlists

Explore the curated watchlists within your organization, offering insights into tracked signals and configurations. This endpoint empowers organizations to efficiently manage and review their signal monitoring setups, ensuring timely and precise oversight.

Responses

Response samples

Content type
application/json

Retrieve Acme Corp's active watchlists for monitoring signals.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Retrieve details of a specific watchlist

This endpoint allows organizations to retrieve comprehensive details of a specific watchlist they own or manage. It empowers users to access critical information such as configuration and status, supporting data-driven decision-making and proactive monitoring.

Responses

Response samples

Content type
application/json

Details of the 'Acme Corp Threat Watchlist'.

{
  • "watchlist_id": "wl-12345",
  • "org_did": "did:org:acme",
  • "name": "Threat Watchlist",
  • "description": "Monitors potential threats to Acme Corp.",
  • "owner_ref": "agent:john.doe",
  • "status": "active",
  • "config": {
    },
  • "created_at": "2023-09-15T08:30:00Z",
  • "updated_at": "2023-10-01T12:00:00Z",
  • "source_ids": [
    ]
}

Update an existing watchlist entry

In the ever-evolving world of AI-human collaboration, keeping track of signals is crucial. This endpoint allows you to update the details of a watchlist, ensuring your team stays informed and agile. Whether it's a name change or a status update, this operation ensures your watchlists reflect the latest intelligence.

Request Body schema: application/json
required
name
string

The new name for the watchlist.

description
string

A brief description of the watchlist.

status
string
Enum: "active" "paused" "archived"

The operational status of the watchlist.

config
object

Configuration settings for the watchlist.

Responses

Request samples

Content type
application/json

This example demonstrates updating the name and status of a watchlist.

{
  • "name": "High Priority Signals",
  • "status": "active"
}

Response samples

Content type
application/json

Key signals for top-tier clients.

null

Remove a watchlist from signals

Effortlessly manage your signal monitoring by removing watchlists no longer needed, ensuring your human-AI orchestration remains efficient and focused. This endpoint allows organizations to delete outdated or irrelevant watchlists, keeping their signal tracking streamlined.

Responses

Response samples

Content type
application/json

Confirmation of watchlist removal.

null

Update sources in a watchlist

This endpoint redefines the sources linked to a specific watchlist, allowing organizations to dynamically adjust their surveillance scope. By managing these sources, businesses can precisely tailor their signal monitoring to stay ahead in their domain.

Request Body schema: application/json
required
source_ids
required
Array of strings

A list of source IDs that the watchlist should monitor.

Responses

Request samples

Content type
application/json

This example updates a watchlist with multiple sources.

{
  • "source_ids": [
    ]
}

Response samples

Content type
application/json

Monitoring key market indicators.

null

Feed

Retrieve curated signals feed

Dive into the dynamic world of AI and human collaboration by accessing a curated feed of signals. This endpoint empowers organizations to filter and analyze signals based on watchlists, event types, verdicts, and confidence levels. It exists to provide transparency and actionable insights, ensuring that organizations can make informed decisions swiftly.

Responses

Response samples

Content type
application/json

An example response showing a list of signals for an organization with pagination.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Create a new signal feed entry

The POST /v1/signals/feed endpoint allows organizations to manually ingest new signals into the HUMAN platform. By crafting a feed entry, organizations can showcase their capabilities, demonstrate prowess, and ensure their skills are recognized in the HUMAN ecosystem.

Request Body schema: application/json
required
title
required
string

Title of the signal.

description
required
string

Detailed description of the signal.

timestamp
required
string <date-time>

The time at which the signal was generated.

tags
Array of strings

Tags categorizing the signal.

Responses

Request samples

Content type
application/json

This example demonstrates how an organization might submit a signal for an AI capability demonstration.

{
  • "title": "AI Capability Demonstration",
  • "description": "A demonstration of AI capabilities integrating HUMAN Passport and Capability Graph.",
  • "timestamp": "2023-09-15T14:30:00Z",
  • "tags": [
    ]
}

Response samples

Content type
application/json
null

Retrieve signal details from feed

Delve into the heartbeat of your organization by fetching detailed insights from the signal feed. This endpoint allows you to track pivotal events and analyze their importance for strategic decision-making, ensuring every action is informed by data-driven intelligence.

Responses

Response samples

Content type
application/json
{
  • "signal_id": "12345",
  • "org_did": "did:example:org123",
  • "source_id": "source789",
  • "watchlist_id": "watchlist456",
  • "event_type": "anomaly_detected",
  • "entity_ref": "entity:acme:invoice:67890",
  • "title": "Unexpected Invoice Surge",
  • "summary": "A sudden increase in invoice submissions was detected.",
  • "confidence": 0.92,
  • "relevance_score": 0.85,
  • "verdict": "review_required",
  • "artifact_ids": [
    ],
  • "metadata": { },
  • "occurred_at": "2023-10-15T14:48:00Z",
  • "created_at": "2023-10-15T15:00:00Z"
}

Deliveries

Retrieve specific webhook delivery details

Uncover the story behind your webhook delivery attempts by retrieving detailed information on a specific delivery using its unique ID. This endpoint allows organizations to audit their webhook deliveries, track attempts, and gain insights into potential issues.

Responses

Response samples

Content type
application/json

Details of a successful webhook delivery retrieval for organization 'acme'.

{
  • "deliveryId": "del_123456",
  • "subscriptionId": "sub_987654",
  • "eventId": "evt_13579",
  • "status": "delivered",
  • "targetUrl": "https://webhooks.acme.com/events",
  • "attemptCount": 1,
  • "maxAttempts": 3,
  • "nextAttemptAt": null,
  • "lastHttpStatus": 200,
  • "lastResponseBody": "OK",
  • "lastError": null,
  • "lastAttemptedAt": "2023-10-12T14:48:00Z",
  • "idempotencyKey": "idemp_2468",
  • "createdAt": "2023-10-10T09:00:00Z",
  • "updatedAt": "2023-10-12T14:48:00Z"
}

Delivery

Retry delivery of failed webhooks

In the ever-evolving landscape of automated tasks, not everything goes as planned. This endpoint allows you to breathe life back into previously failed or 'dead' webhook deliveries, setting them on the path to success once more. It's a second chance for your integrations to communicate effectively.

Responses

Response samples

Content type
application/json

Shows a webhook delivery that has been successfully queued for a retry.

{
  • "delivery_id": "123e4567-e89b-12d3-a456-426614174000",
  • "status": "pending",
  • "redelivered_at": "2023-10-01T12:00:00Z"
}

HUMAN Protocol

Emit Tenant-Safe Telemetry Events

Harness the power of telemetry by securely emitting tenant-specific events into the HUMAN platform's telemetry bus. This endpoint facilitates the tracking of diverse activities within an organization, empowering informed decision-making and AI orchestration.

Request Body schema: application/json
required
event_type
required
string

The type of event being recorded, e.g., 'invoice_processed'.

payload
object

Additional data related to the event, allowing for context-rich telemetry.

subject
string

An optional subject identifier related to the event, such as a user ID.

idempotency_key
string

A unique key to ensure idempotency of event emission.

emitter_agent_did
required
string

DID of the agent emitting this event. Can be inferred from delegation constraints.

Responses

Request samples

Content type
application/json

Example showing a telemetry event for an invoice processing action.

{
  • "event_type": "invoice_processed",
  • "payload": {
    },
  • "subject": "user-6789",
  • "idempotency_key": "key-unique-001",
  • "emitter_agent_did": "did:example:agent123"
}

Response samples

Content type
application/json
{
  • "event_id": "evt-98765",
  • "created_at": "2023-10-12T07:20:50.52Z"
}

Refresh Eligibility Evidence Snapshot

In the dynamic world of Human-AI collaboration, it's crucial to ensure that opportunities are matched with the right skills at the right time. This endpoint recalculates the eligibility evidence for a specific opportunity type, ensuring that your HUMAN Passport reflects the most current skill-to-task alignment and readiness for new challenges.

Request Body schema: application/json
required
passport_did
required
string

The Decentralized Identifier (DID) of the HUMAN Passport.

opportunity_type
string
Default: "workforce_task"

The type of opportunity for which to refresh eligibility.

Responses

Request samples

Content type
application/json

Recomputing eligibility for a workforce task using a specific passport DID.

{
  • "passport_did": "did:human:123456789abcdefghi",
  • "opportunity_type": "workforce_task"
}

Response samples

Content type
application/json
{
  • "passport_did": "did:human:123456789abcdefghi",
  • "opportunity_type": "workforce_task",
  • "computed_at": "2023-10-05T14:48:00.000Z",
  • "eligibility_status": "eligible"
}

DeviceManagement

Update Device Metadata Seamlessly

Enhance your device management by updating specific metadata properties effortlessly. This endpoint allows organizations to refine device configurations, such as setting or clearing the intent dispatch URL, which is crucial for diagnostic probes. By keeping your device metadata up-to-date, you maintain seamless command plane operations.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json

Set the intent dispatch URL for diagnostics.

{}

Response samples

Content type
application/json
{}

Testing

Initiate a Webhook Subscription Test

This endpoint allows organizations to queue a synthetic test delivery for their webhook subscriptions. It's a powerful tool to ensure that your webhook configurations are correctly set up and ready to receive events. By simulating a webhook event, organizations can verify the integrity and responsiveness of their integrations.

Request Body schema: application/json
required
orgDid
required
string

Decentralized identifier for the organization initiating the test

Responses

Request samples

Content type
application/json

Example of a request to initiate a test delivery for webhook subscription with a valid org DID.

{
  • "orgDid": "did:example:123456789abcdefghi"
}

Response samples

Content type
application/json
null

Test Workflow Execution

Initiate a test run of a specific workflow, allowing you to simulate different execution modes to evaluate workflow logic before full deployment. This endpoint empowers organizations to ensure their workflows operate as expected, mitigating risks in live environments.

Request Body schema: application/json
required
mode
required
string
Enum: "dry_run" "sample_data" "live_safe"

Execution mode for the workflow test. Defaults to 'dry_run' if not specified.

Responses

Request samples

Content type
application/json

A test execution in 'dry_run' mode

{
  • "mode": "dry_run"
}

Response samples

Content type
application/json
{
  • "mode": "dry_run",
  • "steps": [
    ],
  • "duration_ms": 125,
  • "lifecycle_state": "draft"
}

Workflow Control

Resume an Interrupted Agent Execution

In the fast-paced world of AI orchestration, interruptions can occur. This endpoint allows you to resume an agent’s workflow that was previously paused, ensuring seamless continuity in your operations. By providing a decision or input, you breathe life back into your processes, picking up precisely where they left off.

Request Body schema: application/json
required
resume_value
required
string

The decision or input required to resume the checkpoint.

Responses

Request samples

Content type
application/json

Resuming an invoice processing agent with the manager's approval decision.

{
  • "resume_value": "approved"
}

Response samples

Content type
application/json
{
  • "checkpoint_id": "chkpt_12345",
  • "status": "resumed",
  • "resumed_at": "2023-10-12T08:45:00Z"
}

Workflow Builder

Create a new Builder workflow

Embark on a journey to orchestrate tasks with ease by creating a new Builder workflow. This endpoint empowers organizations to define and manage workflows, streamlining operations and enhancing productivity. Whether you're just starting with a draft or deploying a full-fledged workflow, this endpoint is your gateway to efficient task orchestration.

Request Body schema: application/json
required
name
string

The display name of the workflow. Defaults to 'Untitled workflow'.

scope
string
Enum: "personal" "workspace" "org"

Defines the visibility scope of the workflow. Defaults to 'workspace'.

manifest
object

A detailed JSON object representing the workflow's structure.

lifecycle_state
string

The current lifecycle state of the workflow, e.g., 'draft'. Defaults to 'draft'.

Responses

Request samples

Content type
application/json

This example demonstrates creating a draft workflow with default settings.

{
  • "name": "Invoice Processing",
  • "scope": "workspace",
  • "manifest": {
    },
  • "lifecycle_state": "draft"
}

Response samples

Content type
application/json
{
  • "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "org_id": "org-1a2b3c",
  • "owner_did": "did:human:123456789abcdefghi",
  • "name": "Invoice Processing",
  • "scope": "workspace",
  • "lifecycle_state": "draft",
  • "manifest": {
    },
  • "version": 1,
  • "builder_flags": { },
  • "published_at": null,
  • "activated_at": null,
  • "created_at": "2023-10-10T14:48:00Z",
  • "updated_at": "2023-10-10T14:48:00Z"
}

Intent

Initiate workflow intent creation

Embark on the journey of crafting a new workflow intent, a crucial step in automating human-AI collaboration. This endpoint enables you to define the blueprint for a workflow, setting the stage for seamless orchestration and task execution.

Request Body schema: application/json
required
name
required
string

The name of the workflow intent

description
string

A detailed description of what the workflow intends to achieve

capabilityGraph
required
Array of strings

Responses

Request samples

Content type
application/json

An example of creating a workflow intent for processing invoices in the 'acme' organization.

{
  • "name": "Invoice Processing",
  • "description": "Handles the processing of invoices submitted by vendors.",
  • "capabilityGraph": [
    ]
}

Response samples

Content type
application/json
null

Retrieve Intent Briefs for an Organization

Delve into the orchestration of Human-AI collaboration by fetching intent briefs that guide AI interactions. This endpoint is crucial for organizations looking to monitor and enhance AI-driven workflows, by providing insights derived from the Capability Graph.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Ingest multimodal intent data

This endpoint allows organizations to seamlessly ingest diverse forms of intent data—be it text, documents, or audio. By processing multimodal inputs, HUMAN enhances the efficiency of task orchestration and ensures that AI models are trained with the richest possible datasets.

Request Body schema: application/json
required
One of
text
required
string

The raw text of the intent.

document_text
string

A textual document representing the intent.

audio_base64
string

Base64-encoded audio data.

source_surface
string
Enum: "companion" "control_plane" "workflow_designer" "agent_builder"

The origin of the intent submission.

Responses

Request samples

Content type
application/json

Submitting a simple text intent from the companion surface.

{
  • "text": "How to process invoices more efficiently?",
  • "source_surface": "companion"
}

Response samples

Content type
application/json
{
  • "brief": {
    },
  • "needs_clarification": false,
  • "clarification_questions": [ ]
}

Retrieve intent lineage details for analysis

Uncover the historical context and evolution of a specific intent within the HUMAN platform. This endpoint provides a comprehensive lineage, detailing its versions, associated resolution plans, and related artifacts. This insight is crucial for organizations aiming to audit or enhance their Human-AI orchestration strategies.

Responses

Response samples

Content type
application/json

Fetching the lineage for an intent used in Acme Corp's invoice processing.

{
  • "intent_brief": {
    },
  • "versions": [
    ],
  • "resolution_plan": {
    },
  • "scaffolded_artifacts": [
    ],
  • "execution_runs": [ ],
  • "approvals": [ ],
  • "audit_event_ids": [
    ]
}

Retrieve audit trail for Intent

Explore the history of an Intent, capturing its evolutionary journey through different versions and compilations. This endpoint provides a detailed audit trail, showcasing how an Intent has been shaped and compiled over time, ensuring transparency and traceability in decision-making.

Responses

Response samples

Content type
application/json
{
  • "intent_brief_id": "123e4567-e89b-12d3-a456-426614174000",
  • "versions": [
    ],
  • "compilations": [
    ],
  • "provenance_capabilities": [
    ],
  • "query_provenance": {
    }
}

Generate an Intent Scaffold

This endpoint breathes life into raw intent by transforming it into a scaffold. By orchestrating organizational capabilities and aligning them with intent, it ensures a seamless path from concept to execution. It's where ideas meet structured implementation.

Request Body schema: application/json
required
override_capability_ids
Array of strings <uri> [ items <uri > ]

A list of capability URIs to override the default selection.

Responses

Request samples

Content type
application/json

Overrides default capabilities with specified URIs.

{
  • "override_capability_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "scaffold": {
    }
}

Simulate intent execution for analysis

Dive into the future with intent simulations, allowing organizations to preview the outcomes of their strategies before they are executed. This endpoint exists to empower decision-makers, providing them insight and foresight by simulating complex scenarios using the HUMAN platform's orchestration capabilities.

Responses

Response samples

Content type
application/json

Simulates a strategy for the 'acme' organization to process invoices, projecting high success.

{
  • "simulation": {
    }
}

Companion

Create workflow from Companion suggestion

This endpoint empowers organizations to transform AI-driven insights from the HUMAN Companion into executable workflows. By bridging AI suggestions with organizational processes, it orchestrates a seamless integration ensuring efficiency and innovation.

Request Body schema: application/json
required
suggested_intent
string

AI suggested intent for the workflow.

intent_brief_id
string

Optional ID of an existing intent brief.

Responses

Request samples

Content type
application/json

An example where a new workflow is suggested by the AI companion.

{
  • "suggested_intent": "Automate invoice processing",
  • "intent_brief_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json

A successful response with a new workflow manifest and IDs.

{
  • "manifest": {
    },
  • "intent_brief_id": "123e4567-e89b-12d3-a456-426614174000",
  • "resolution_plan_id": "plan-9876",
  • "source": "intent_scaffold"
}

Retrieve personalized companion preferences

Unveil a world tailored to your preferences by fetching your companion settings. This endpoint is your gateway to understanding how HUMAN customizes interactions, ensuring a seamless and personal experience orchestrated with AI precision.

Responses

Response samples

Content type
application/json

An example of a user's companion preferences within Acme Corp.

{}

Update Companion Preferences

Tailor your AI companion to your liking by updating its preferences. This endpoint allows you to set the tone, formality, and other attributes of your companion, ensuring it aligns with your personal or organizational style.

Request Body schema: application/json
required
handle
string or null

Unique identifier for the companion

humor_level
string
Enum: "none" "low" "medium" "high"

Humor intensity

formality
string
Enum: "informal" "formal"

Formality level of interactions

verbosity
string
Enum: "concise" "detailed"

Preferred verbosity of responses

domain_context
string or null

Domain-specific context for interactions

custom_instructions
string or null

Custom instructions for the companion

starter_mode
string or null
Enum: "beginner" "intermediate" "advanced"

Starter mode of the companion

onboarding_started_at
string or null <date-time>

Timestamp when onboarding started

onboarding_completed_at
string or null <date-time>

Timestamp when onboarding completed

onboarding_steps_completed
Array of strings

Steps completed in onboarding

first_artifact_delivered
string or null

Timestamp of first artifact delivery

workflow_activations
Array of strings

Activated workflows

academy_opens
Array of strings

Academy opens

reentry_hint_delivered
boolean

Reentry hint status

Responses

Request samples

Content type
application/json

Sets humor to medium and formality to informal for a more casual interaction style.

{
  • "handle": "chatbot123",
  • "humor_level": "medium",
  • "formality": "informal"
}

Response samples

Content type
application/json
{
  • "handle": "chatbot123",
  • "humor_level": "medium",
  • "formality": "informal",
  • "verbosity": "detailed",
  • "domain_context": null,
  • "custom_instructions": null,
  • "starter_mode": "intermediate",
  • "onboarding_started_at": "2023-10-01T12:00:00Z",
  • "onboarding_completed_at": "2023-10-02T12:00:00Z",
  • "onboarding_steps_completed": [
    ],
  • "first_artifact_delivered": "2023-10-03T12:00:00Z",
  • "workflow_activations": [
    ],
  • "academy_opens": [ ],
  • "reentry_hint_delivered": true,
  • "passport_display_name": "John Doe",
  • "avatar_url": "https://example.com/avatar.jpg",
  • "email": "john.doe@example.com",
  • "preferred_language": "en"
}

Record Turn-Level Conversation Patterns

This endpoint allows the HUMAN Companion agent to observe and record conversational patterns between users and AI assistants, capturing the essence of human-AI interaction. By analyzing these patterns, the system enhances its understanding, enabling more personalized and context-aware responses in future interactions.

Request Body schema: application/json
required
user_text
required
string

The text input by the user.

assistant_text
required
string

The response generated by the AI assistant.

turn_id
string

A unique identifier for the conversation turn.

Responses

Request samples

Content type
application/json

Captures a user's query and assistant's response in a turn.

{
  • "user_text": "What's the weather like today?",
  • "assistant_text": "It's sunny and 75 degrees.",
  • "turn_id": "turn_1698771202931"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "recorded": [
    ]
}

Retrieve pending user preferences

Uncover the hidden preferences waiting to enhance your conversation experience. This endpoint helps users explore personalized settings that have yet to be confirmed, ensuring their interactions are tailored to their unique style. The magic lies in uncovering what your AI companion has learned about your preferences, fostering a more engaging dialogue.

Responses

Response samples

Content type
application/json

Illustrates a typical response with a pending preference suggestion.

{
  • "pending": {
    }
}

Acknowledge companion preferences signal

This endpoint acknowledges a specific signal related to companion preferences, allowing the system to either save or skip the action based on user input. It's a crucial touchpoint for ensuring user preferences are respected in the orchestration of human and AI interactions.

Request Body schema: application/json
required
signal_id
required
string

The unique identifier for the signal.

action
required
string
Enum: "save" "skip"

Action to perform on the signal, either 'save' or 'skip'.

Responses

Request samples

Content type
application/json

An example where the user acknowledges a signal with the 'save' action.

{
  • "signal_id": "abc123",
  • "action": "save"
}

Response samples

Content type
application/json

The response on successfully acknowledging a signal with 'save'.

{
  • "ok": true,
  • "signal": {
    }
}

Retrieve curated companion discussion topics

Explore a diverse array of conversation starters designed to enhance interactions between humans and AI. This endpoint empowers users to engage with the HUMAN platform by providing dynamic and contextually relevant topics tailored to their interests. Whether you're a developer or an end-user, these topics help you unlock the full potential of AI interactions, fostering creativity and collaboration.

Responses

Response samples

Content type
application/json

A user retrieves a list of topics for a seamless companion experience.

{
  • "data": [
    ],
  • "limit": 50,
  • "cursorFields": [
    ],
  • "hasMore": true
}

Create or Update Companion Topics

This endpoint allows you to create or update topics associated with a user's companion profile. By harnessing the power of categorization, it enables a richer, more personalized interaction between humans and AI. Elevate your user experience by tailoring interactions based on the topics that matter most.

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json

Adding topics related to a user's interests and preferences.

{
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Remove a companion chat topic

Effortlessly retire a conversation topic and make room for new ideas in your chat. This endpoint ensures only authorized users can manage topics, preserving the integrity of your discussions.

Responses

Response samples

Content type
application/json

The chat topic with ID 'topic123' was successfully deleted.

{
  • "ok": true,
  • "topic_id": "topic123"
}

Respond to a C2C message

Orchestrate the dance between humans and AI by responding to a Message using HUMAN's dynamic protocol. Whether accepting, rejecting, or countering, this endpoint ensures the conversation continues with purpose and clarity.

Request Body schema: application/json
required
action
required
string
Enum: "accept" "reject" "counter"

The decision on the message: 'accept', 'reject', or 'counter'.

reason
string

Optional explanation for the chosen action.

Responses

Request samples

Content type
application/json
Example

Shows a response where the user accepts a message with no additional comment.

{
  • "action": "accept"
}

Response samples

Content type
application/json
null

Retrieve Companion Profile by Handle

Discover a Companion's profile by resolving their unique handle. This endpoint is vital for organizations to seamlessly integrate with their Companions, ensuring smooth operations and collaboration. By connecting with a Companion's profile, organizations can tap into a rich network of skills and capabilities.

Responses

Response samples

Content type
application/json
{
  • "passport_did": "did:human:123456789abcdefghi",
  • "handle": "john_doe",
  • "display_name": "John Doe",
  • "role": "Developer",
  • "avatar_url": "https://avatars.example.com/john_doe.png",
  • "is_active": true,
  • "companion_endpoint": "https://companion.example.com",
  • "public_key": "abc123xyz789",
  • "last_seen_at": "2023-10-01T12:34:56Z",
  • "notification_preferences": {
    }
}

Retrieve available companion commands

Explore the dynamic world of HUMAN's AI by retrieving a list of commands that your organization can execute. This endpoint empowers you with the knowledge of available operations, enabling seamless integration and orchestration of tasks between humans and AI.

Responses

Response samples

Content type
application/json

A sample response showing the first page of available commands.

{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "eyJwcyI6IjEyMyIsInEiOiJBTkFMWVpFX0lOVk9JQ0UifQ=="
}

Retrieve Companion Session Details

Uncover the details of your current Companion session, revealing the cryptographic identity and active interactions. This endpoint is essential for organizations to manage their AI and human collaboration securely.

Responses

Response samples

Content type
application/json
{
  • "companion_agent_did": "did:human:agent:1234567890abcdef",
  • "org_did": "did:human:org:acme-corp",
  • "passport_did": "did:human:passport:user123",
  • "active_subscriptions_count": 5
}

Subscribe to Companion Events

Empower your organization with dynamic event subscriptions, seamlessly connecting your AI and human capabilities. The endpoint crafts a bridge between your systems and Companion, fostering intelligent task orchestration.

Request Body schema: application/json
required
event_pattern
required
string

A pattern that matches the events to subscribe to.

source_connector_id
string

Identifier for the source connector related to the event.

label
string

An optional label to identify the subscription.

Responses

Request samples

Content type
application/json

Subscribe to invoice processing events from a specific source.

{
  • "event_pattern": "invoice.*",
  • "source_connector_id": "acme_finance_connector",
  • "label": "Invoice Subscription"
}

Response samples

Content type
application/json
{
  • "subscription_id": "sub-1234567890",
  • "event_pattern": "invoice.*",
  • "source_connector_id": "acme_finance_connector",
  • "label": "Invoice Subscription",
  • "created_at": "2023-10-15T12:34:56Z"
}

Retrieve active agent-trigger subscriptions

Dive into the orchestration of AI and human tasks by exploring the active subscriptions for agent-triggered events. This endpoint illuminates the path of notifications as they journey through the HUMAN ecosystem, ensuring tasks are efficiently routed and executed.

Responses

Response samples

Content type
application/json

Acme Corp's agent-triggered subscriptions for their invoice processing workflow.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Deactivate a Companion Subscription

This endpoint empowers organizations to gracefully deactivate a subscription linked to their Companion. By ensuring subscriptions are only paused when needed, it maintains resource efficiency and security.

Responses

Response samples

Content type
application/json

A successful deactivation of a subscription by the 'acme' organization.

{
  • "subscription_id": "sub_123abc",
  • "status": "inactive"
}

Retrieve Inbound Companion Events

Dive into the world of asynchronous task orchestration with this endpoint, designed to unearth completed inbound events from the HUMAN platform. This endpoint is vital for organizations using the HUMAN protocol to seamlessly integrate and track event triggers orchestrated by AI, ensuring that no completed task goes unnoticed.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Builder

Retrieve a specific workflow by ID

Discover the intricate details of a workflow by retrieving it using its unique identifier. This endpoint is a gateway to understanding how your organization's workflows are orchestrated, ensuring seamless task execution.

Responses

Response samples

Content type
application/json

An example showing successful retrieval of a workflow

{
  • "id": "wf1234",
  • "name": "Invoice Processing",
  • "status": "active",
  • "created_at": "2023-09-15T12:34:56Z",
  • "updated_at": "2023-10-01T08:45:23Z"
}

Update an existing workflow definition

In the world of dynamic task orchestration, workflows are the heart of managing complex processes. This endpoint empowers organizations to update these workflows, ensuring they adapt to evolving business requirements while maintaining the integrity of their lifecycle states.

Request Body schema: application/json
required
name
required
string

Human-readable name for the workflow

manifest
object

JSON object representing the workflow's structure and logic

lifecycle_state
string
Enum: "draft" "active" "archived"

Current state of the workflow in its lifecycle

builder_flags
object

Additional flags for workflow builder settings

Responses

Request samples

Content type
application/json

This example demonstrates updating the name and state of a workflow

{
  • "name": "Invoice Processing Workflow",
  • "lifecycle_state": "active",
  • "manifest": {
    },
  • "builder_flags": {
    }
}

Response samples

Content type
application/json
{
  • "id": "wf-12345",
  • "name": "Invoice Processing Workflow",
  • "manifest": {
    },
  • "lifecycle_state": "active",
  • "builder_flags": {
    }
}

Delete a Builder Workflow by ID

In the dynamic world of workflow automation, maintaining a clean slate is crucial. This endpoint empowers organizations to remove obsolete or incorrect workflows, ensuring their operational landscape remains efficient and relevant. By providing this ability, we help teams focus on what matters most: innovation and productivity.

Responses

Response samples

Content type
application/json
null

Duplicate an existing workflow

This endpoint allows you to create a new copy of an existing workflow within your organization, enabling iterative development and experimentation. By duplicating workflows, you can preserve original configurations while exploring new ideas, enhancing collaboration and innovation.

Request Body schema: application/json
required
name_suffix
string

Suffix to append to the original workflow name

Responses

Request samples

Content type
application/json

Duplicates a workflow with a custom suffix appended to the name

{
  • "name_suffix": " - new iteration"
}

Response samples

Content type
application/json

Response after successfully duplicating a workflow

{
  • "id": "workflow-1234",
  • "name": "Invoice Processing - new iteration",
  • "owner_did": "did:human:123456789abcdef",
  • "scope": "accounting",
  • "lifecycle_state": "draft"
}

RunHistory

Retrieve Workflow Run History

Unlock the past of your automation endeavors with this endpoint, allowing organizations to delve into the historical runs of specified workflows. By tracking these runs, you can learn from past outcomes, ensuring continuous improvement and refined orchestration strategies.

Responses

Response samples

Content type
application/json

An example of a successful response listing workflow runs.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "started_at",
  • "hasMore": false
}

Policy

Retrieve available policy packs

Explore the curated collection of policy packs designed to enhance your Human-AI orchestration with standardized governance and compliance measures. This endpoint is your gateway to understanding the safeguards in place for secure and auditable AI operations.

Responses

Response samples

Content type
application/json

An example of a policy pack with governance features.

{
  • "data": [
    ]
}

Validate human policy structure

In the ever-evolving landscape of AI collaborations, ensuring that policies are structured correctly is paramount. This endpoint invites organizations to validate their policy documents, ensuring they meet the cryptographic standards required for secure, efficient AI orchestration. By confirming the validity of these policies, organizations can trust in a seamless integration with HUMAN's distributed ledger.

Request Body schema: application/json
required
required
object

The policy document to validate.

Responses

Request samples

Content type
application/json

A sample policy document from Acme Corp undergoing validation.

{
  • "policy": {
    }
}

Response samples

Content type
application/json
{
  • "valid": true
}

Retrieve Effective HumanOS Policy

Discover the confluence of organizational directives within the HUMAN platform. This endpoint reveals the effective HumanOS policy, interwoven with organizational overlays, offering insights into AI task governance and safety protocols.

Responses

Response samples

Content type
application/json

Fetching the effective HumanOS policy for Acme Corporation.

{
  • "policy_version": "1.4.5",
  • "fourth_law_confidence_threshold": 0.85,
  • "learning_requires_approval": true,
  • "learning": {
    },
  • "merged_policy": {
    },
  • "policy_resolution": {
    }
}

SkillTracking

Capture Skill Event with Builder Completion

This endpoint allows the HUMAN platform to record the completion of an AcademyMoment by a user, along with any associated skill signals. It enhances the platform's knowledge about a user's capabilities and progress, ensuring a more personalized and effective task routing experience.

Request Body schema: application/json
required
user_did
string

The decentralized identifier (DID) of the user. Optional if delegation is provided.

skill_id
required
string

The identifier for the skill being logged.

event_type
required
string

The type of event being recorded, such as 'completion' or 'initiation'.

context
object

Additional context about the event, provided as a key-value map.

Responses

Request samples

Content type
application/json

Logs a skill completion event for a user with a corresponding skill and context.

{
  • "user_did": "did:example:123456789abcdefghi",
  • "skill_id": "skill:acme:invoice-processing",
  • "event_type": "completion",
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "id": "evt_01F8ZK9Z4TJ1T9Y3V7Q4GV8G5D",
  • "occurred_at": "2023-10-15T14:50:00.000Z"
}

Import

Import and draft external workflow

Breathe life into your workflow library by importing external agent or workflow definitions. This endpoint empowers organizations to craft an initial draft of a builder workflow, ensuring seamless integration with existing processes. Whether you're migrating with capability overrides or specifying platform hints, this operation is your gateway to a refined orchestration setup.

Request Body schema: application/json
required
payload
required
string

Base64 encoded agent or workflow definition.

platform_hint
string

Optional hint about the target platform.

object

Optional per-step capability overrides.

name
string

Optional workflow name. Defaults to 'Imported workflow'.

Responses

Request samples

Content type
application/json

Import a basic workflow with no platform hint or overrides.

{
  • "payload": "c29tZS1iYXNlNjQtcGF5bG9hZA==",
  • "name": "Invoice Processor"
}

Response samples

Content type
application/json
{
  • "workflow_id": "wf_12345",
  • "builder_url": "https://console.haio.run/builder/wf_12345",
  • "rung": 2,
  • "step_summary": {
    },
  • "warnings": [
    ],
  • "suggested_connectors": [
    ]
}

Import capability definitions into HUMAN

Effortlessly expand your HUMAN capabilities by importing definitions. This endpoint empowers organizations to seamlessly introduce new capability structures, ensuring that your AI-human collaborations remain cutting-edge and adaptable. Whether you're avoiding conflicts or overwriting existing entries, this tool is designed to enhance your capability graph with ease.

Request Body schema: application/json
required
required
Array of objects

Array of capability definitions to be imported

conflict_strategy
string
Enum: "skip" "overwrite" "fail"

Strategy to handle conflicts with existing definitions

scope
string
Enum: "canonical" "org"

Scope of the import operation

Responses

Request samples

Content type
application/json

Example showing a typical import with conflict resolution strategy

{
  • "definitions": [
    ],
  • "conflict_strategy": "overwrite",
  • "scope": "org"
}

Response samples

Content type
application/json
null

Analysis

Preview migration of workflows and agents

Embark on a journey to modernize your workflows effortlessly with this endpoint. By analyzing the structure and components of your intended migration, it offers insights into potential steps, prompts, and warnings, all while ensuring no data is prematurely committed. This vital preview phase helps you make informed decisions before taking the plunge with POST /import.

Request Body schema: application/json
required
platform
required
string

The target platform for migration.

required
object

Details of the workflow to be migrated.

Responses

Request samples

Content type
application/json

A simple workflow migration to the 'acme' platform.

{
  • "platform": "acme",
  • "workflow": {
    }
}

Response samples

Content type
application/json
{
  • "stats": {
    },
  • "steps": [
    ],
  • "prompts": [
    ],
  • "warnings": [
    ]
}

Analyze capability gaps for target roles

The gap analysis endpoint evaluates the Learning Capability Evidence Framework (LCEF) portfolio against a specified target role or capability. By understanding these gaps, organizations can tailor training to help individuals achieve their desired roles.

Responses

Response samples

Content type
application/json

Evaluates the gaps in a portfolio for transitioning to a Data Analyst role.

{
  • "target_role": "Data Analyst",
  • "gap_summary": {
    },
  • "next_best_proof": [
    ]
}

Real-Time Updates

Stream Workforce Work Item Updates

Dive into the heart of your operations by streaming real-time updates for a specific work item. This endpoint ensures you're always in sync, providing live status changes and actions performed on your work items, crucial for time-sensitive tasks and responsive workflows.

Responses

Response samples

Content type
application/json
{
  • "event": "connected",
  • "data": {
    }
}

Recovery

Approve recovery request as guardian

This endpoint empowers guardians to affirm their role in the recovery process, crucial for securing cryptographic identities within the HUMAN platform. By approving a recovery request, guardians help ensure that only authorized users can reclaim their digital identities, safeguarding against unauthorized access or loss.

Request Body schema: application/json
required
shard_b64
string

Plaintext shard in base64url encoding, required in SSS mode.

signature
string

Optional signature for audit trail in attestation mode.

Responses

Request samples

Content type
application/json
Example

Guardian approving with a plaintext shard in SSS mode.

{
  • "shard_b64": "c2hhcmRTYW1wbGU"
}

Response samples

Content type
application/json

A guardian's approval has been successfully processed.

{
  • "request_id": "req_12345",
  • "approvals_received": 3,
  • "approvals_required": 5,
  • "threshold_met": false,
  • "lock_until": "2023-12-31T12:00:00Z",
  • "ready_to_complete": false
}

Approve a Passport Recovery Request

This endpoint allows a guardian or delegating entity to approve a recovery request for a Passport. By validating the integrity and authority of the actor, it ensures that the process of regaining access is securely handled and protected against unauthorized actions.

Responses

Response samples

Content type
application/json

The recovery request has been approved by the guardian.

{
  • "request_id": "req-12345",
  • "approvals": 3,
  • "required": 3,
  • "status": "approved"
}

Execute a Passport Recovery Request

When human and AI collide, passports need recovery. Execute an approved recovery request to breathe life back into your digital identity. This endpoint ensures seamless recovery, verifying security at each step, and offers a second chance for your cryptographic identity.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json

An example WebAuthn payload for human recovery

{
  • "webauthn": {
    }
}

Response samples

Content type
application/json
{
  • "passport_id": "did:example:123456789abcdefghi",
  • "status": "executed",
  • "next_step": "recovery_complete",
  • "auth_key_id": "key-12345",
  • "attest_key_id": "key-67890",
  • "retired_at": "2023-10-15T14:48:00.000Z"
}

Initiate guardian-mediated recovery process

Embark on a journey to reclaim control of your cryptographic identity through the trusted hands of your appointed guardians. This endpoint kicks off a guardian-mediated recovery process, locking the Passport for a 48-hour window, ensuring security and deliberate action.

Request Body schema: application/json
required
reason
string

The reason for initiating recovery. Helps guardians understand the context.

completion_mode
required
string
Enum: "server_assembly" "client_proof"

Defines the completion process, either controlled by the server or client.

Responses

Request samples

Content type
application/json

Initiate recovery because the user lost access to their Passport.

{
  • "reason": "Lost access to Passport",
  • "completion_mode": "server_assembly"
}

Response samples

Content type
application/json

The request was processed, and the recovery sequence has begun.

{
  • "message": "Guardian recovery process initiated successfully.",
  • "lock_period": 48
}

Retrieve Encrypted Shamir Shard for Recovery

Guardians play a crucial role in the HUMAN network, ensuring the security and recovery of cryptographic identities. This endpoint allows a guardian to access their encrypted Shamir shard, a vital piece for identity recovery. Once decrypted client-side, the shard helps reconstruct the user's identity, safeguarding against data loss.

Responses

Response samples

Content type
application/json
{
  • "request_id": "req_123456",
  • "shard_index": 2,
  • "encrypted_shard_b64": "c2hhcmRfZW5jcnlwdGVkX2RhdGE=",
  • "ephemeral_public_key_b64": "ZXBoZW1lcmFsX3B1YmtleQ==",
  • "iv_b64": "aW5pdGlhbF92ZWN0b3I="
}

Submit Shard for Guardian Recovery

Embark on a journey of digital resurrection as you submit the vital cryptographic shard needed for recovering a lost device. This endpoint ensures that the guardians of your identity unite to restore access, maintaining the sanctity of your cryptographic Passport.

Request Body schema: application/json
required
proof_of_reconstruction
required
string

Proof that the shards have been correctly reassembled

new_device_public_key
required
string

Public key of the new device being registered

registration_id
required
string

Registration identifier for the new device

required
object

Credential object or WebAuthn attestation

object

WebAuthn attestation details, alternative to credential

Responses

Request samples

Content type
application/json

A valid submission with all required fields

{
  • "proof_of_reconstruction": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "new_device_public_key": "04bfcab2f53a...",
  • "registration_id": "reg-12345",
  • "credential": {
    }
}

Response samples

Content type
application/json
{
  • "status": "Recovery process initiated successfully"
}

Accept Guardian Role for Passport Recovery

In the intricate dance of Human-AI orchestration, ensuring a secure recovery process is paramount. This endpoint allows a guardian to accept their role in the recovery of a passport, downloading an encrypted shard bundle to their device. By acknowledging this responsibility, guardians protect the sanctity of digital identities.

Responses

Response samples

Content type
application/json

A guardian successfully accepts their role and receives the encrypted shard.

{
  • "request_id": "req_12345",
  • "passport_did": "did:human:abc123",
  • "guardian_did": "did:human:guardian456",
  • "shard_index": 1,
  • "encrypted_shard_b64": "VGhpcyBpcyBhbiBlbmNyeXB0ZWQgc2hhcmQ=",
  • "ephemeral_public_key_b64": "RW5jcnlwdGVkIFB1YmxpYyBLZXk=",
  • "iv_b64": "SW5pdCBWZWN0b3I=",
  • "delivered_to_device": true
}

Relay Guardian Ciphertext for Recovery

This endpoint allows a Guardian to post a ciphertext for a device attempting to recover a Passport identity. It plays a crucial role in ensuring that the right credentials are securely relayed, maintaining the integrity and security of identity recovery in the HUMAN platform.

Request Body schema: application/json
required
payload_b64
required
string

Base64-encoded ciphertext for the recovering device.

Responses

Request samples

Content type
application/json

An example where a Guardian submits the required ciphertext for a recovery process.

{
  • "payload_b64": "c29tZS1lbmNvZGVkLWNpcGhlcnRleHQ="
}

Response samples

Content type
application/json

A successful response indicating the ciphertext was relayed.

{
  • "ok": true,
  • "request_id": "request-12345",
  • "guardian_did": "did:example:guardian-6789"
}

Retrieve Passport Recovery Shard Signals

In a world where identity recovery is paramount, this endpoint empowers the passport holder to retrieve shard signals vital for reconstructing their cryptographic identity. It ensures the safe delivery of pending ciphertext payloads, marking them as received.

Responses

Response samples

Content type
application/json

Shows a successful retrieval of shard signals.

{
  • "request_id": "req-123456789",
  • "signals": [
    ]
}

WebAuthn

Initiate WebAuthn login challenge

Embark on a secure journey of authentication with WebAuthn. This endpoint crafts a unique challenge for users aiming to log in via public-key credentials, ensuring a robust identity verification process. It's the first step in fortifying your digital space with cryptographic assurance.

Request Body schema: application/json
required
One of
passport_hint
required
string

A hint for the passport, such as an email.

Responses

Request samples

Content type
application/json
Example

An example showcasing the use of snake_case passport_hint.

{
  • "passport_hint": "user@example.com"
}

Response samples

Content type
application/json

A typical response showing the generated challenge and options for a user attempting login.

{
  • "challenge_id": "challenge_1234567890abcdef",
  • "options": {
    }
}

Authenticate using WebAuthn and issue JWT

Seamlessly authenticate users by verifying a WebAuthn assertion and issuing a short-lived JWT session token. This endpoint safeguards digital identities using cryptographic validation, ensuring only verified users can access sensitive delegation exchanges.

Request Body schema: application/json
required
challenge_id
required
string

Unique identifier for the WebAuthn challenge

credential
required
object

WebAuthn credential assertion object

Responses

Request samples

Content type
application/json

A typical request using a WebAuthn credential to authenticate.

{
  • "challenge_id": "ch_1234567890abcdef",
  • "credential": {
    }
}

Response samples

Content type
application/json

The response returned after a successful authentication.

{
  • "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "passport_id": "did:human:123456789abcdef",
  • "did": "did:human:123456789abcdef",
  • "display_name": "Alice Doe",
  • "verification_tier": "verified",
  • "identity_tier": "silver",
  • "expires_at": "2023-10-01T12:00:00Z"
}

User Management

Modify User Passport Information

Empower users to customize their digital identity by updating fields like avatar and display name. This fosters a personalized experience while maintaining strict security protocols, ensuring only the rightful owner can make changes.

Request Body schema: application/json
required
avatar_url
string or null <uri>

URL of the user's avatar image

display_name
string

The name displayed on the user's profile

email
string or null <email>

User's contact email

preferred_language
string or null^[a-z]{2,3}(-[A-Z]{2,4})?$

Preferred language in BCP-47 format

Responses

Request samples

Content type
application/json

An update where the user changes their avatar and display name

{}

Response samples

Content type
application/json
{
  • "passport_id": "did:human:abc123",
  • "display_name": "Jane Doe",
  • "avatar_url": "https://example.com/images/avatar.png",
  • "email": "jane.doe@example.com",
  • "preferred_language": "en",
  • "updated_at": "2023-10-01T12:00:00Z"
}

Remove user preferences by Passport DID

This endpoint allows an organization to wipe user preferences using a Passport DID, ensuring compliance with privacy requests or resets. It's a crucial part of maintaining user autonomy and organizational data integrity.

Responses

Response samples

Content type
application/json

User preferences and signals were successfully cleared for the given Passport DID.

{
  • "ok": true,
  • "target_passport_did": "did:human:123456",
  • "cleared": {
    },
  • "reset_by": "did:human:654321"
}

Passports

Retrieve Passport's Verification Status

Explore the journey of a passport as it climbs the Validity Ladder, unlocking new capabilities at each tier. This endpoint reveals the layers of verification and identity tiers achieved by a passport, enabling clients to guide users through potential upgrades.

Responses

Response samples

Content type
application/json

The verification and identity status for Acme Corp's passport, highlighting unlocked and gated capabilities.

{
  • "did": "did:human:acme12345",
  • "verification_tier": 2,
  • "identity_tier": 1,
  • "layers": {
    },
  • "identity_tiers": {
    },
  • "capabilities_unlocked": [
    ],
  • "capabilities_gated": [
    ]
}

Approve a Passport Recovery Request

This endpoint allows a guardian or delegating entity to approve a recovery request for a Passport. By validating the integrity and authority of the actor, it ensures that the process of regaining access is securely handled and protected against unauthorized actions.

Responses

Response samples

Content type
application/json

The recovery request has been approved by the guardian.

{
  • "request_id": "req-12345",
  • "approvals": 3,
  • "required": 3,
  • "status": "approved"
}

Log consent events with provenance tracking

In the HUMAN ecosystem, consent is more than agreement—it's a critical piece of provenance. This endpoint logs consent events, optionally registering them as capability evidence if they grant a specific capability. By doing so, it not only ensures compliance but also empowers participants by securely documenting their consent footprint.

Request Body schema: application/json
required
action
string

The action associated with the consent, if any.

capabilityGranted
string

The capability ID granted by this consent, if applicable.

required
object

Responses

Request samples

Content type
application/json

Logging consent for an organization to access a user's profile data.

{
  • "action": "access_profile",
  • "capabilityGranted": "capability://acme/profile_access",
  • "consentEntry": {
    }
}

Response samples

Content type
application/json
{
  • "consent_id": "consent-12345",
  • "provenance_id": "prov-67890",
  • "capability_evidence_registered": true,
  • "status": "recorded"
}

Retrieve details of an org proposal

Explore the intricacies of a specific proposal within an organization's capability graph. By fetching these details, stakeholders can review, approve, or track the status and history of skill changes, ensuring transparency and accountability in decision-making.

Responses

Response samples

Content type
application/json
{
  • "proposal_id": "abc123",
  • "org_did": "did:human:org:acme",
  • "change_type": "skill_upgrade",
  • "proposed_by": "did:human:agent:jdoe",
  • "payload": {
    },
  • "status": "pending",
  • "approvals": [
    ],
  • "approvals_collected": 1,
  • "threshold_required": 3,
  • "created_at": "2023-09-28T09:45:00Z",
  • "expires_at": "2023-10-05T09:45:00Z",
  • "executed_at": null,
  • "provenance_id": "prov123"
}

Initiate a device sync session for a Passport

Embarking on a new journey with your Passport's devices, this endpoint initiates a synchronization process. It ensures that only authorized devices can partake in this dance of data, safeguarding your cryptographic identity with precision and trust.

Request Body schema: application/json
required
initiating_device_id
required
string

The ID of the device initiating the sync.

current_device_signature
required
string

The JWS signature from the current device.

ephemeral_public_key
required
string

Ephemeral public key for secure communication.

p2p_capable
boolean

Flag indicating if the session supports peer-to-peer mode.

Responses

Request samples

Content type
application/json

Initiating a sync session with essential details and optional P2P capability.

{
  • "initiating_device_id": "device123",
  • "current_device_signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "ephemeral_public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQ...",
  • "p2p_capable": true
}

Response samples

Content type
application/json
{
  • "session_id": "sess-abc123",
  • "qr_payload": {
    },
  • "expires_at": "2023-11-15T15:00:00Z",
  • "p2p_mode": true,
  • "signal_url": "/v1/passports/did%3Ahuman%3A1234/devices/sync/sess-abc123/signal"
}

Retrieve Passport's Latest Ledger Anchor

Unlock the cryptographic trail of your identity with this endpoint, offering a peek into the most recent ledger anchor of a Human Passport. This ensures trust and transparency as you explore the digital provenance of skills and tasks.

Responses

Response samples

Content type
application/json
{
  • "did": "did:human:123456789abcdefghi",
  • "anchor_id": "anchor123",
  • "batch_id": "batch456",
  • "merkle_root": "abcd1234efgh5678ijkl9101mnopqrst",
  • "merkle_proof": [
    ],
  • "leaf_index": 1,
  • "leaf_hash": "mnop1234qrst5678",
  • "transaction_hash": "tx1234567890abcdef",
  • "block_number": 123456,
  • "chain_id": 42,
  • "chain_name": "Ethereum Mainnet",
  • "anchored_at": "2023-10-01T12:00:00Z"
}

Signal device sync for passport session

This endpoint is a digital bridge connecting devices within a user's cryptographic identity, enabling them to exchange signaling information securely. By allowing devices to sync signals like 'offer', 'answer', or 'ice-candidate', it ensures seamless interaction and coordination within the HUMAN network, enhancing efficiency and safety.

Request Body schema: application/json
required
type
required
string
Enum: "offer" "answer" "ice-candidate"

The type of signal being sent

payload
required
string

The signaling payload data to be transmitted

from_device_id
required
string

Identifier of the device sending the signal

Responses

Request samples

Content type
application/json

A device sends an offer to initiate a WebRTC connection

{
  • "type": "offer",
  • "payload": "v=0\r\n...",
  • "from_device_id": "device-123"
}

Response samples

Content type
application/json

Devices successfully exchanged signaling information

{
  • "signals": [
    ]
}

Retrieve synchronized signals for device

Harness the potential of secure identity with HUMAN's Passport by retrieving synchronized signals for a specific device session. This endpoint empowers users to poll device signals, ensuring that only authorized individuals can access their cryptographic identities' data.

Responses

Response samples

Content type
application/json

An example showing successfully fetched signals for a session.

{
  • "signals": [
    ]
}

Relay Guardian Ciphertext for Recovery

This endpoint allows a Guardian to post a ciphertext for a device attempting to recover a Passport identity. It plays a crucial role in ensuring that the right credentials are securely relayed, maintaining the integrity and security of identity recovery in the HUMAN platform.

Request Body schema: application/json
required
payload_b64
required
string

Base64-encoded ciphertext for the recovering device.

Responses

Request samples

Content type
application/json

An example where a Guardian submits the required ciphertext for a recovery process.

{
  • "payload_b64": "c29tZS1lbmNvZGVkLWNpcGhlcnRleHQ="
}

Response samples

Content type
application/json

A successful response indicating the ciphertext was relayed.

{
  • "ok": true,
  • "request_id": "request-12345",
  • "guardian_did": "did:example:guardian-6789"
}

Retrieve Active Principals for Passport

Uncover the identities your passport can embody, from personal to organizational alignments. This endpoint reveals all active principals linked to the authenticated passport, allowing you to navigate your roles with clarity.

Responses

Response samples

Content type
application/json

Retrieve principals for a passport linked to personal identity and Acme Corp.

{
  • "principals": [
    ],
  • "active_principal_id": "did:human:passport:123456789abcdef"
}

Retrieve delegation grants for a passport

Explore the cryptographic relationships that bind humans and AI by retrieving delegation grants for your authenticated passport. This endpoint allows you to track the web of trust and capabilities extended and received, helping to ensure that every interaction is secure and verifiable.

Responses

Response samples

Content type
application/json

Retrieve active delegation grants, showcasing the permissions Acme Corp has granted to various agents.

{
  • "data": [
    ],
  • "limit": 20,
  • "hasMore": false
}

Passport Management

Revoke a Passport Key

Securely revoke a cryptographic key associated with a Passport, ensuring it can no longer be used for authentication. This endpoint is vital for maintaining security and control over access, especially in dynamic environments where keys must be invalidated promptly.

Responses

Response samples

Content type
application/json
{
  • "passport_id": "passport_12345",
  • "key_id": "key_67890",
  • "status": "revoked",
  • "revoked_at": "2023-11-05T14:48:00.000Z"
}

Initiate Passport Recovery Process

Create a recovery request to regain access to a cryptographic passport, ensuring identity continuity in secure environments. This endpoint is the first step in safeguarding and restoring access when a passport is compromised or lost, leveraging HUMAN's robust identity framework.

Request Body schema: application/json
required
expiresAt
string <date-time>

The expiration date and time of the recovery request. If not provided, defaults to a predefined TTL.

reason
required
string

The reason for initiating this recovery request, providing context for auditing.

Responses

Request samples

Content type
application/json

An example where the recovery request is created for a lost passport.

{
  • "expiresAt": "2023-12-31T23:59:59Z",
  • "reason": "Lost access to my cryptographic key"
}

Response samples

Content type
application/json
{
  • "request_id": "req_1234567890",
  • "status": "pending",
  • "policy_id": "pol_0987654321",
  • "expires_at": "2023-12-31T23:59:59Z"
}

Retrieve founders of an organization passport

Behind every successful organization is a team of founders whose vision shapes its identity. This endpoint allows you to explore the individuals who established a given organization, identified by its decentralized identifier (DID). By understanding who these founders are, you gain insight into the organization's origin story and governance structure.

Responses

Response samples

Content type
application/json

Example showing the retrieval of founders for the organization 'acme'

{
  • "org_did": "did:org:acme",
  • "legal_name": "Acme Corp",
  • "status": "active",
  • "founders": [
    ],
  • "founder_count": 2
}

Consent

Log consent events with provenance tracking

In the HUMAN ecosystem, consent is more than agreement—it's a critical piece of provenance. This endpoint logs consent events, optionally registering them as capability evidence if they grant a specific capability. By doing so, it not only ensures compliance but also empowers participants by securely documenting their consent footprint.

Request Body schema: application/json
required
action
string

The action associated with the consent, if any.

capabilityGranted
string

The capability ID granted by this consent, if applicable.

required
object

Responses

Request samples

Content type
application/json

Logging consent for an organization to access a user's profile data.

{
  • "action": "access_profile",
  • "capabilityGranted": "capability://acme/profile_access",
  • "consentEntry": {
    }
}

Response samples

Content type
application/json
{
  • "consent_id": "consent-12345",
  • "provenance_id": "prov-67890",
  • "capability_evidence_registered": true,
  • "status": "recorded"
}

Create a Consent Policy for a Passport

This endpoint allows a passport holder to define consent policies that dictate how their data can be accessed. By automating approval or denial of specific claims, users maintain control over their digital identity while reducing manual intervention.

Request Body schema: application/json
required
claim_names
required
Array of strings

A non-empty array of claims that this policy applies to

action
required
string
Enum: "auto_approve" "auto_deny"

The action to take when the claims match this policy

requester_did_pattern
string

An optional pattern to match requesters by their DID

purpose_pattern
string

An optional pattern describing the purpose context

priority
integer

The priority of this policy, with lower numbers indicating higher priority

Responses

Request samples

Content type
application/json

Creates a policy to auto-approve access for specific claims

{
  • "claim_names": [
    ],
  • "action": "auto_approve",
  • "requester_did_pattern": "did:human:org:test",
  • "purpose_pattern": "data:access",
  • "priority": 50
}

Response samples

Content type
application/json
{
  • "id": "policy-123",
  • "passport_did": "did:human:example:123456",
  • "requester_did_pattern": "did:human:org:test",
  • "claim_names": [
    ],
  • "purpose_pattern": "data:access",
  • "action": "auto_approve",
  • "priority": 50,
  • "created_at": "2023-10-01T12:34:56Z"
}

Retrieve consent policies for a passport

Dive into the intricate world of consent management with HUMAN's Passport Consent Policies. This endpoint allows you to explore the nuanced policies that govern what claims and actions are automatically approved or denied for a specific passport. Empowering users and organizations, it ensures transparency and control over data sharing.

Responses

Response samples

Content type
application/json

Acme Corp is reviewing its consent policies for compliance and data governance.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Remove a user's consent policy

In the HUMAN protocol, consent is crucial. This endpoint allows the owner of a cryptographic identity, or Passport, to remove a consent policy they've previously granted. It's a step towards empowering users by giving them control over their personal data and how it's shared.

Responses

Response samples

Content type
application/json

The consent policy with ID 'policy-1234-5678' was successfully removed.

{
  • "ok": true,
  • "id": "policy-1234-5678"
}

Proposals

Retrieve organization's proposal list with pagination

Explore the dynamic landscape of organizational progress by retrieving a list of proposals associated with a decentralized identifier (DID). This endpoint empowers organizations to track proposed changes, ensuring informed decision-making and transparent governance.

Responses

Response samples

Content type
application/json

A paginated response showing the first page of proposals for the 'acme' organization.

{
  • "data": [
    ],
  • "pagination": {
    }
}

Retrieve details of an org proposal

Explore the intricacies of a specific proposal within an organization's capability graph. By fetching these details, stakeholders can review, approve, or track the status and history of skill changes, ensuring transparency and accountability in decision-making.

Responses

Response samples

Content type
application/json
{
  • "proposal_id": "abc123",
  • "org_did": "did:human:org:acme",
  • "change_type": "skill_upgrade",
  • "proposed_by": "did:human:agent:jdoe",
  • "payload": {
    },
  • "status": "pending",
  • "approvals": [
    ],
  • "approvals_collected": 1,
  • "threshold_required": 3,
  • "created_at": "2023-09-28T09:45:00Z",
  • "expires_at": "2023-10-05T09:45:00Z",
  • "executed_at": null,
  • "provenance_id": "prov123"
}

Reject a proposal within an organization

In the dynamic interplay of human intellect and AI, proposals drive evolution. This endpoint empowers founders to decisively reject proposals that no longer align with organizational vision, ensuring agility and adherence to core values.

Request Body schema: application/json
required
One of
rejected_by
required
string^did:human:.*$

DID of the founder rejecting the proposal

Responses

Request samples

Content type
application/json

Example illustrating rejection by a valid founder DID.

{
  • "rejected_by": "did:human:1234abcd"
}

Response samples

Content type
application/json
{
  • "proposal_id": "proposal-5678efgh",
  • "status": "rejected",
  • "rejected_by": "did:human:1234abcd"
}

Retrieve capability proposals for a DID

Explore the landscape of your digital capabilities with this endpoint. By retrieving proposals associated with a Decentralized Identifier (DID), you can track the evolution of skills and knowledge as they align with your digital identity. This empowers organizations to make informed decisions about skill development and deployment.

Responses

Response samples

Content type
application/json

ACME Corp retrieves the latest 50 capability proposals for DID 'did:example:123456789abcdefghi'.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Accept a Capability Proposal

In the dynamic world of Human-AI collaboration, the acceptance of capability proposals solidifies the partnership between human agents and AI systems. This endpoint empowers authorized reviewers to formally accept proposals, thereby expanding the skill set recognized within the HUMAN platform.

Request Body schema: application/json
required
reviewer_did
required
string

The decentralized identifier of the reviewer accepting the proposal.

Responses

Request samples

Content type
application/json

Acceptance of a capability proposal with a valid reviewer DID.

{
  • "reviewer_did": "did:human:example123"
}

Response samples

Content type
application/json
null

Reject a capability proposal

This endpoint allows a reviewer to reject a capability proposal, ensuring that only appropriate skills are added to the Capability Graph. By empowering reviewers to provide feedback, HUMAN maintains a high standard of trust and reliability in its network.

Request Body schema: application/json
required
reviewer_did
required
string

Decentralized Identifier of the reviewer

rejection_reason
required
string

Reason for rejecting the proposal

Responses

Request samples

Content type
application/json

Rejecting a proposal with a valid reason

{
  • "reviewer_did": "did:human:abc123",
  • "rejection_reason": "Insufficient evidence of skill proficiency"
}

Response samples

Content type
application/json
null

Identity Verification

Initiate Biometric Verification Session

Unlock the next tier of identity verification by initiating a biometric verification session. This endpoint allows passport holders to securely advance their verification and identity tiers to Level 2, using cutting-edge biometric authentication. Experience seamless identity verification with human intelligence and AI safety protocols.

Responses

Response samples

Content type
application/json

A biometric verification session was successfully initiated for the passport holder.

{}

Biometric

Initiate Biometric Verification Session

Unlock the next tier of identity verification by initiating a biometric verification session. This endpoint allows passport holders to securely advance their verification and identity tiers to Level 2, using cutting-edge biometric authentication. Experience seamless identity verification with human intelligence and AI safety protocols.

Responses

Response samples

Content type
application/json

A biometric verification session was successfully initiated for the passport holder.

{}

Trust

Retrieve active vouches for a passport

Explore the trusted network around a passport by listing its active vouches. Discover how others in the HUMAN ecosystem vouch for this identity, building a web of trust that strengthens the protocol's integrity.

Responses

Response samples

Content type
application/json

Retrieve active vouches for the given passport ID

{
  • "data": [
    ],
  • "limit": 10,
  • "next_cursor": null
}

Revoke a self-authored vouch.

In the intricate dance of identity verification, a vouch represents trust. This endpoint allows a voucher to withdraw their endorsement, recalibrating the trust network if necessary. If the withdrawal dips below a critical threshold, the verification tier is gracefully demoted, ensuring the integrity of the ecosystem.

Responses

Response samples

Content type
application/json

A voucher revokes their support for a passport DID, reducing the active vouches.

{
  • "revoked": true,
  • "remaining_active_vouches": 1
}

SharedDocuments

Retrieve documents shared with user

Uncover the vault documents that others have explicitly shared with you. This endpoint empowers the authenticated user by listing shared documents, ensuring you're always in the know. Ideal for collaboration and transparency, it securely returns metadata, omitting encrypted content, and handles pagination gracefully.

Responses

Response samples

Content type
application/json

A list of documents shared with a user from the 'acme' organization.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Disclosure

Create a Passport Disclosure Request

Submit a request for specific attribute disclosures from a HUMAN passport. This endpoint empowers organizations to verify identity claims while respecting user consent and privacy policies, ensuring a secure and transparent process.

Request Body schema: application/json
required
requester_did
required
string

DID of the entity requesting disclosure

requested_claims
required
object

Attributes being requested for disclosure

purpose
required
string

Purpose for requesting the disclosure

expires_in_seconds
required
integer

Time in seconds until the request expires

proof_type
required
string

Type of proof required for the disclosure

range_proofs
object

Optional range proofs for verifying claims

Responses

Request samples

Content type
application/json

A request for verifying age attribute with a proof type of 'zero-knowledge'.

{
  • "requester_did": "did:human:acme:org",
  • "requested_claims": {
    },
  • "purpose": "Verify age for age-restricted service",
  • "expires_in_seconds": 3600,
  • "proof_type": "zero-knowledge",
  • "range_proofs": {
    }
}

Response samples

Content type
application/json
{
  • "request_id": "pdr_12345",
  • "status": "pending",
  • "created_at": "2023-10-01T10:00:00Z",
  • "expires_at": "2023-10-01T11:00:00Z",
  • "proof_type": "zero-knowledge",
  • "consent_policy_id": "policy_6789"
}

Grant Disclosure on Human Passport

Enable trusted sharing of verified capabilities by granting disclosure requests on a Human Passport. This endpoint empowers users to selectively share their validated skills, ensuring transparency and trust in Human-AI collaborations.

Request Body schema: application/json
required
approved_claims
required
Array of strings

List of claims approved for disclosure.

Responses

Request samples

Content type
application/json

A user approves specific claims for an organization.

{
  • "approved_claims": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "Disclosure granted",
  • "granted_claims": [
    ]
}

Retrieve Passport Disclosure Details

Unearth the cryptographic secrets of a Passport with this endpoint, which reveals the story behind a specific disclosure request. This endpoint is your key to understanding the intricate dance of data between a subject and requester, spotlighting the purpose, status, and cryptographic proofs involved.

Responses

Response samples

Content type
application/json

A successful retrieval of a disclosure request for a Passport, with all cryptographic details included.

{
  • "request_id": "12345",
  • "subject_did": "did:human:acme:john.doe",
  • "requester_did": "did:human:acme:trusted.partner",
  • "requested_claims": [
    ],
  • "purpose": "Verification of identity for onboarding",
  • "status": "granted",
  • "created_at": "2023-10-05T12:34:56Z",
  • "expires_at": "2023-12-31T23:59:59Z",
  • "resolved_at": "2023-10-10T14:22:01Z",
  • "proof_type": "bbs",
  • "bbs_credential": {
    },
  • "verifier_challenge": "challenge_string",
  • "disclosed_claims": [
    ]
}

Disclose fields from evidence record

Reveal specific fields from an evidence record, allowing verifiable claims to be shared securely. This endpoint ensures that only authorized users can disclose fields, maintaining the integrity of the evidence while facilitating trusted interactions.

Request Body schema: application/json
required
disclosed_fields
required
Array of strings

List of fields to disclose.

purpose
string

Purpose of the disclosure.

requester_did
string

DID of the entity requesting disclosure.

Responses

Request samples

Content type
application/json

Request to disclose specific fields for verification purposes.

{
  • "disclosed_fields": [
    ],
  • "purpose": "Verification of identity",
  • "requester_did": "did:example:requester123"
}

Response samples

Content type
application/json
{
  • "verifiable_presentation": {
    },
  • "verifier_challenge": "SGVsbG9Xb3JsZA==",
  • "disclosed_fields": [
    ],
  • "issuer_did": "did:example:issuer456",
  • "evidence_record_id": "record789",
  • "purpose": "Verification of identity",
  • "requester_did": "did:example:requester123"
}

Privacy

Deny a disclosure request for a passport

In the dance of identity and privacy, sometimes a request must be refused. This endpoint allows a passport holder to deny a pending disclosure request, ensuring that only the rightful owner can manage their personal information. It's a safeguard in the HUMAN protocol's commitment to user autonomy and privacy.

Responses

Response samples

Content type
application/json
null

Blockchain

Verify Passport Ledger Anchor Inclusion

Ensure your digital identity's anchoring is secure by verifying its inclusion in the blockchain's Merkle tree. This endpoint empowers users to authenticate their Passport's ledger integrity, reinforcing trust in decentralized identity management.

Request Body schema: application/json
required
required
Array of objects
leaf_hash
required
string^0x[a-fA-F0-9]{64}$

Responses

Request samples

Content type
application/json

A valid Merkle proof with corresponding leaf hash for identity verification.

{
  • "merkle_proof": [
    ],
  • "leaf_hash": "0xabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcd"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "on_chain_ref": {
    }
}

FraudDetection

Route fraud case for human intervention

In the intricate dance of AI and human collaboration, this endpoint orchestrates the routing of potential fraud cases to human agents for further investigation. It ensures that suspicious activities don't slip through the cracks of automation, safeguarding the integrity of your operations.

Request Body schema: application/json
required
case_ref
required
string

A unique reference for the fraud case

Responses

Request samples

Content type
application/json

Routing a fraud case with a unique reference to human agents.

{
  • "case_ref": "fraud_case_12345"
}

Response samples

Content type
application/json
{
  • "routing_id": "cp_frt_67890",
  • "case_ref": "fraud_case_12345",
  • "routing_decision": "route_to_human",
  • "reason": "fraud_investigation_default",
  • "fourth_law_triggered": true,
  • "recorded_at": "2023-10-11T08:30:00Z"
}

Risk Assessment

Assess risk of a routed task

Uncover the hidden risks associated with a specific task routed through the HUMAN platform. This endpoint provides a risk score for a task, ensuring that potential issues are flagged early, allowing for proactive management and AI safety.

Responses

Response samples

Content type
application/json

Retrieve risk details for routing ID 12345.

{
  • "routing_id": "12345",
  • "agent_did": "did:human:acme",
  • "task_description": "Invoice processing for client XYZ",
  • "risk_score": 7.5,
  • "scored_at": "2023-10-05T14:48:00.000Z"
}

PolicyManagement

Create a structured HumanOS policy

Define structured policies within the HumanOS to govern task execution with precision. This endpoint empowers organizations to craft policies that ensure AI safety and task orchestration fidelity. By harnessing the protocol, you create robust governance frameworks that align with organizational objectives.

Request Body schema: application/json
required
name
required
string

A unique name for the policy.

required
object

The policy document detailing rules and parameters.

team_id
string

Identifier for the team the policy applies to.

agent_did
string

Decentralized Identifier for the agent responsible for the policy.

active
boolean

Flag indicating if the policy is active.

Responses

Request samples

Content type
application/json

This example demonstrates creating a new policy for invoice processing.

{
  • "name": "Invoice Processing Policy",
  • "policy": {
    },
  • "team_id": "team-1234",
  • "agent_did": "did:human:agent-5678",
  • "active": true
}

Response samples

Content type
application/json
{
  • "policy_id": "policy-12345",
  • "name": "Invoice Processing Policy",
  • "version": 1,
  • "active": true,
  • "created_at": "2023-10-30T14:12:00Z"
}

TaskRouting

Route batch tasks through HumanOS

The batch-route endpoint empowers organizations to efficiently direct multiple tasks through HumanOS, leveraging AI-driven orchestration for safe and effective task execution. This endpoint underlines the platform's commitment to scalability and precision, optimizing the management of up to 50 tasks in a single request.

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json

Submitting a batch of tasks for AI routing within 'acme' organization.

{
  • "tasks": [
    ]
}

Response samples

Content type
application/json

All tasks in the batch are successfully processed.

{
  • "results": [
    ],
  • "batch_size": 2
}

Route tasks with AI safety protocols

The POST /v1/humanos/routing endpoint orchestrates task routing within the HumanOS ecosystem, ensuring AI safety and accountability. By leveraging cryptographic identities and capability graphs, it guarantees secure and efficient human-AI collaboration. This endpoint is essential for organizations seeking to balance human intuition with AI precision.

Request Body schema: application/json
required
task_id
required
string

Unique identifier for the task.

task_type
required
string

Type of task to be routed, defining required skills.

Responses

Request samples

Content type
application/json

Routes a data processing task for the 'acme' organization.

{
  • "task_id": "12345",
  • "task_type": "data_processing"
}

Response samples

Content type
application/json
{
  • "status": "routed",
  • "task_id": "12345",
  • "orgDid": "did:example:acme"
}

Retrieve task routing history for organization

Explore the journey of tasks as they dance through the intricate choreography of HumanOS. This endpoint unveils the past decisions and confidence levels that guided tasks, providing insights into the orchestration process and the AI's role in task routing.

Responses

Response samples

Content type
application/json

A snapshot of Acme Corp's task routing history showing the status and decisions made for recent tasks.

{
  • "data": [
    ],
  • "limit": 2,
  • "cursorFields": [
    ],
  • "hasMore": true
}

AI Safety

Route tasks with AI safety protocols

The POST /v1/humanos/routing endpoint orchestrates task routing within the HumanOS ecosystem, ensuring AI safety and accountability. By leveraging cryptographic identities and capability graphs, it guarantees secure and efficient human-AI collaboration. This endpoint is essential for organizations seeking to balance human intuition with AI precision.

Request Body schema: application/json
required
task_id
required
string

Unique identifier for the task.

task_type
required
string

Type of task to be routed, defining required skills.

Responses

Request samples

Content type
application/json

Routes a data processing task for the 'acme' organization.

{
  • "task_id": "12345",
  • "task_type": "data_processing"
}

Response samples

Content type
application/json
{
  • "status": "routed",
  • "task_id": "12345",
  • "orgDid": "did:example:acme"
}

History

Retrieve task routing history for organization

Explore the journey of tasks as they dance through the intricate choreography of HumanOS. This endpoint unveils the past decisions and confidence levels that guided tasks, providing insights into the orchestration process and the AI's role in task routing.

Responses

Response samples

Content type
application/json

A snapshot of Acme Corp's task routing history showing the status and decisions made for recent tasks.

{
  • "data": [
    ],
  • "limit": 2,
  • "cursorFields": [
    ],
  • "hasMore": true
}

Escalation

Create a new escalation rule

In the HUMAN realm, routing tasks safely and efficiently often demands escalation. This endpoint empowers organizations to define rules that trigger when conditions warrant human intervention, ensuring seamless task management and AI oversight.

Request Body schema: application/json
required
name
required
string

A unique name for the escalation rule.

conditions
object

Conditions under which the escalation rule is triggered.

Responses

Request samples

Content type
application/json

An example rule that triggers when default conditions are met.

{
  • "name": "Urgent Task Escalation",
  • "conditions": {
    }
}

Response samples

Content type
application/json

A successful response indicating a new rule was created.

{
  • "rule_id": "hos_rule_123456",
  • "name": "Urgent Task Escalation",
  • "created_at": "2023-10-01T12:00:00Z"
}

Manually escalate tasks for human oversight

In the dynamic realm of HUMAN's orchestration, this endpoint enables organizations to manually escalate tasks requiring human intervention. It ensures that critical tasks are handled with the attention they demand, combining the power of AI with the wisdom of human judgment.

Request Body schema: application/json
required
reason
required
string

The reason for escalating this task, providing context for human intervention.

task_type
string

The type of task being escalated, helping route to the appropriate human agent.

routing_id
string

An identifier for the routing of the task, ensuring precise tracking.

object

Additional context for the escalation, allowing for a richer understanding of the situation.

Responses

Request samples

Content type
application/json

Escalating an invoice processing task due to complex discrepancy.

{
  • "reason": "Discrepancy in invoice data requires human review.",
  • "task_type": "invoice_processing",
  • "routing_id": "task-12345",
  • "context": {
    }
}

Response samples

Content type
application/json
null

Safety

Evaluate HumanOS task safety checks

This endpoint assesses whether a specific action within a given domain complies with the organization's HumanOS safety policies. By evaluating these actions, HumanOS ensures that tasks are performed within the ethical and procedural boundaries set by the organization, protecting both human and AI participants.

Request Body schema: application/json
required
domain
required
string
Default: "general"

Domain of the action, e.g., 'finance' or 'general'

action
required
string
Default: "unknown"

Specific action to be evaluated, e.g., 'processInvoice'

Responses

Request samples

Content type
application/json

Check safety for processing an invoice in the finance domain.

{
  • "domain": "finance",
  • "action": "processInvoice"
}

Response samples

Content type
application/json
{
  • "allowed": true,
  • "domain": "finance",
  • "action": "processInvoice",
  • "reasons": [
    ],
  • "reviewed_at": "2023-10-01T12:34:56Z"
}

Retrieve HumanOS Safety Configuration

Uncover the safety protocols that guide HumanOS in safeguarding your organization’s tasks. This endpoint provides an organization-specific configuration that aligns AI task routing with safety policies, ensuring secure and efficient operations.

Responses

Response samples

Content type
application/json

Acme Corporation's safety configuration for HumanOS task routing.

{
  • "config": {
    },
  • "org_scoped": true
}

Learning

Retrieve learning pointers with pagination

Explore the learning index to discover pointers associated with your organization's skillset. This endpoint serves as the navigator through the knowledge network, providing entries that match your criteria. Perfect for organizations aiming to streamline their AI-enabled learning pathways.

Responses

Response samples

Content type
application/json

A list of learning pointers for the 'acme' organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": true,
  • "cursorFields": [
    ],
  • "totalCount": null
}

Retrieve learning proposals with pagination

In a world where human expertise meets AI orchestration, learning proposals are the blueprints for adaptive growth. This endpoint allows organizations to fetch these proposals, ensuring they harness the right skills at the right time. Pagination and status filtering provide fine-tuned control over the data flow.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "total_count": null
}

Draft a new learning proposal

Create a draft proposal to orchestrate human learning tasks with AI safety. This endpoint empowers organizations to define and track skills development initiatives, ensuring each proposal is routed efficiently while maintaining a secure and auditable trail.

Request Body schema: application/json
required
proposal_kind
required
string

The type of learning proposal being created.

scope
string

The scope of the proposal, defaults to 'org'.

passport_did
string

The cryptographic identity of the passport associated with the proposal.

approval_request_id
string

ID for the approval request, if applicable.

source_feedback_ids
Array of integers

Identifiers for feedback sources related to the proposal.

expires_at
string <date-time>

The expiration timestamp for the proposal.

payload
object

Additional data associated with the proposal.

object (LearningExplainMetadata)

Optional explain metadata on learning proposals (POST /v1/humanos/learning/proposals) and embedded in humanos_tuning_actions.payload after apply. Validated with LearningExplainMetadataSchema in @human/humanos; unknown keys are stripped.

Responses

Request samples

Content type
application/json

A simple draft proposal for a new training module.

{
  • "proposal_kind": "new_training_module",
  • "scope": "org",
  • "passport_did": "did:human:123456789abcdefghi",
  • "approval_request_id": "approval-6789",
  • "source_feedback_ids": [
    ],
  • "expires_at": "2023-12-31T23:59:59Z",
  • "payload": {
    },
  • "explain": {
    }
}

Response samples

Content type
application/json
{
  • "proposal_id": "lrp-20231001-abc123",
  • "org_did": "did:human:org123",
  • "status": "draft",
  • "proposal_kind": "new_training_module",
  • "payload": {
    },
  • "explain": {
    },
  • "approval_request_id": "approval-6789",
  • "source_feedback_ids": [
    ],
  • "expires_at": "2023-12-31T23:59:59Z",
  • "created_at": "2023-10-01T12:00:00Z",
  • "updated_at": "2023-10-01T12:00:00Z"
}

Retrieve a specific learning proposal.

Fetch details of a learning proposal for an organization in the HUMAN network, empowering you to track AI skill enhancements with precision and accountability. Understand the status, scope, and feedback of your proposals at a glance, ensuring your initiatives align with organizational goals.

Responses

Response samples

Content type
application/json

An example of a learning proposal retrieved for the Acme Corp organization.

{
  • "proposal_id": "abc123",
  • "org_did": "did:human:acme",
  • "passport_did": "did:human:john.doe",
  • "scope": "AI skill enhancement",
  • "status": "approved",
  • "proposal_kind": "training",
  • "payload": {
    },
  • "explain": {
    },
  • "approval_request_id": "req-456def",
  • "source_feedback_ids": [
    ],
  • "expires_at": "2024-01-01T00:00:00Z",
  • "created_at": "2023-08-15T12:00:00Z",
  • "updated_at": "2023-09-01T08:30:00Z"
}

Roll back a learning proposal

This endpoint empowers organizations to roll back previously applied learning proposals within HumanOS. By reversing an applied proposal, the system ensures flexibility and adaptability in dynamic environments, allowing for strategic pivots when necessary.

Responses

Response samples

Content type
application/json

Example of a successful rollback of a learning proposal.

{
  • "proposal_id": "abc123",
  • "status": "rolled_back",
  • "compensating_tuning_action_id": "tun567",
  • "scope": "org",
  • "superseded_tuning_action_id": "tun789"
}

Infer learning proposals from feedback

Harness the power of collective intelligence by transforming feedback into actionable learning proposals. This endpoint analyzes recent feedback events within your organization to suggest improvements, helping you stay ahead in a rapidly evolving landscape.

Request Body schema: application/json
required
limit
integer [ 1 .. 100 ]

Maximum number of feedback events to process. Defaults to 20 if not specified.

Responses

Request samples

Content type
application/json

Request to process up to 30 feedback events.

{
  • "limit": 30
}

Response samples

Content type
application/json
{
  • "org_did": "did:example:123456789abcdef",
  • "drafts": [
    ],
  • "feedback_rows_considered": 30
}

Learning Proposals

Update Learning Proposal Status

Navigate the complex journey of transforming a learning proposal's status with precision. This endpoint empowers you to orchestrate seamless transitions, ensuring that proposals progress through the appropriate lifecycle stages while maintaining compliance with server-enforced status transitions.

Request Body schema: application/json
required
status
required
string
Enum: "draft" "pending_review" "approved" "rejected" "applied" "rolled_back"

The new status for the proposal.

approval_request_id
string or null

Optional ID for an approval request related to this status change.

Responses

Request samples

Content type
application/json

This example demonstrates updating a proposal status from 'draft' to 'pending_review' with an associated approval request.

{
  • "status": "pending_review",
  • "approval_request_id": "approval-1234"
}

Response samples

Content type
application/json
null

Risk Management

Calibrate audit event risk embeddings

Enhance your audit insights by recalibrating the risk scores of humanos audit events with fresh embeddings. This endpoint exists to ensure your risk assessment remains accurate and up-to-date, leveraging the power of AI for more precise decision-making.

Request Body schema: application/json
required
mode
string
Enum: "full" "incremental"

Determines whether to perform a full recalibration or an incremental update.

limit
integer [ 1 .. 500 ]
Default: 100

Limits the number of events processed in this request.

after_id
integer

The ID to start processing from, for pagination purposes.

Responses

Request samples

Content type
application/json

Requests a full recalibration of audit events with a limit of 200.

{
  • "mode": "full",
  • "limit": 200
}

Response samples

Content type
application/json
null

Cryptography

Retrieve BBS+ Issuer Verification Key

Unveil the powerful BBS+ issuer verification key, designed for offline verifiers to ensure trust without the tether of constant connectivity. By accessing this endpoint, you empower decentralized identity systems to validate credentials authentically and securely.

Responses

Response samples

Content type
application/json

Retrieve the BBS+ issuer verification key for offline verification.

{
  • "keys": [
    ]
}

Verify Disclosed Evidence Presentation

Unveil the truth behind cryptographic evidence by verifying its disclosed claims against a BBS+ anchor. This endpoint safeguards the integrity of digital credentials, ensuring trust and transparency in decentralized identity systems.

Request Body schema: application/json
required
presentation
required
object

BBS+ cryptographic presentation object

verifier_challenge
required
string

Challenge string used by the verifier

Responses

Request samples

Content type
application/json

A complete and valid BBS+ presentation with a verifier challenge

{
  • "presentation": {
    },
  • "verifier_challenge": "random-challenge-string"
}

Response samples

Content type
application/json

The presentation is valid with disclosed fields

{
  • "valid": true,
  • "disclosed_fields": [
    ],
  • "issuer_did": "did:example:123456789abcdefghi",
  • "error": null
}

Sync

Signal device sync for passport session

This endpoint is a digital bridge connecting devices within a user's cryptographic identity, enabling them to exchange signaling information securely. By allowing devices to sync signals like 'offer', 'answer', or 'ice-candidate', it ensures seamless interaction and coordination within the HUMAN network, enhancing efficiency and safety.

Request Body schema: application/json
required
type
required
string
Enum: "offer" "answer" "ice-candidate"

The type of signal being sent

payload
required
string

The signaling payload data to be transmitted

from_device_id
required
string

Identifier of the device sending the signal

Responses

Request samples

Content type
application/json

A device sends an offer to initiate a WebRTC connection

{
  • "type": "offer",
  • "payload": "v=0\r\n...",
  • "from_device_id": "device-123"
}

Response samples

Content type
application/json

Devices successfully exchanged signaling information

{
  • "signals": [
    ]
}

Revocation

Fetch Passport Device Revocation Snapshot

Retrieve a cryptographic snapshot of revoked devices for a given Human Passport. This endpoint empowers offline verifiers by providing them with a cached list of device IDs that have been revoked, ensuring the integrity and validity of AI orchestrations.

Responses

Response samples

Content type
application/json

Fetching the revocation snapshot for an active passport.

{
  • "passport_did": "did:human:123456789abcdefghi",
  • "revoked_device_ids": [
    ],
  • "snapshot_at": "2023-10-15T12:00:00.000Z",
  • "expires_at": "2023-10-16T12:00:00.000Z",
  • "content_sha256": "5d41402abc4b2a76b9719d911017c592",
  • "hub_public_key": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQD...",
  • "hub_signature": "MEUCIQDy9...aR+Q==",
  • "canonical_message": "revocation-snapshot|did:human:123456789abcdefghi|2023-10-15T12:00:00.000Z|5d41402abc4b2a76b9719d911017c592"
}

Decisions

Retrieve and explain an audit decision

Unravel the intricacies of a specific audit decision by fetching its detailed explanation. This endpoint empowers organizations to understand the outcomes of their decision-making processes, ensuring transparency and accountability in the orchestration of human and AI interactions.

Responses

Response samples

Content type
application/json

An example response for a successful audit decision explanation retrieval.

{
  • "decision_id": "12345",
  • "summary": "Approved invoice processing",
  • "policy_version_snapshot": "v2023.10.01",
  • "escalation_occurred": false,
  • "override_occurred": true,
  • "integrity_status": "verified",
  • "evidence_status": "complete"
}

Retrieve decision audit by ID

Dive into the depths of decision-making with the HUMAN platform's decision audit retrieval. This endpoint lets you explore the intricate web of decisions made within your organization, ensuring transparency and traceability in a world increasingly driven by AI and human collaboration. Whether you are validating an audit grant or simply accessing your own decision history, this endpoint guarantees that every decision is accounted for.

Responses

Response samples

Content type
application/json

A comprehensive audit of a decision within the 'acme' organization, showcasing the decision's origins and lifecycle.

{
  • "id": "dec-12345",
  • "title": "Approve Invoice Payment",
  • "workflow_id": "wf-67890",
  • "org_did": "did:human:acme",
  • "decision_type": "Approval",
  • "status": "Completed",
  • "risk_level": "Low",
  • "policy_checks": [
    ],
  • "escalation_occurred": false,
  • "override_occurred": false,
  • "provenance_chain_id": "chain-12345",
  • "actors": [
    ],
  • "graph_execution_id": "exec-54321",
  • "created_at": "2023-10-01T10:00:00Z",
  • "updated_at": "2023-10-02T12:00:00Z",
  • "escalation_events": [ ],
  • "override_events": [ ],
  • "redacted_count": 0,
  • "redacted_reason": ""
}

Retrieve audit decision details by ID

Dive into the history of an organization's decision-making process by fetching detailed records of audit decisions. This endpoint reveals the intricacies of decision provenance, ensuring transparency and accountability in AI-assisted operations.

Responses

Response samples

Content type
application/json

Shows a complete audit decision for organization 'acme'.

{
  • "id": "dec123",
  • "title": "Invoice Review",
  • "workflow_id": "wf456",
  • "org_did": "did:human:acme",
  • "decision_type": "approval",
  • "status": "completed",
  • "risk_level": "low",
  • "policy_checks": [ ],
  • "escalation_occurred": false,
  • "override_occurred": false,
  • "provenance_chain_id": "chain789",
  • "actors": [ ],
  • "graph_execution_id": "exec101",
  • "policy_version_snapshot": "v1.0",
  • "integrity_status": "verified",
  • "created_at": "2023-10-02T14:48:00Z",
  • "updated_at": "2023-10-02T15:00:00Z"
}

Attestations

Identify Missing Audit Attestations

In the vast landscape of audit trails, some stones are left unturned. This endpoint shines a light on the gaps in your audit attestations, ensuring every decision is verified. By identifying where attestations are missing, organizations can maintain integrity and trust in their processes.

Responses

Response samples

Content type
application/json

An example response where certain attestations are missing.

{
  • "data": [
    ],
  • "scanned_decisions": 150,
  • "missing_count": 2
}

Comparison

Compare Two Audit Decision Chains

Dive deep into decision-making by comparing two audit decision chains. Unveil the differences in policies, workflows, and overrides to ensure your organization’s audits are transparent and accountable.

Request Body schema: application/json
required
decision_id_a
required
string

Unique identifier for the first decision

decision_id_b
required
string

Unique identifier for the second decision

Responses

Request samples

Content type
application/json

Compares two decisions to identify changes in policy versions and overrides.

{
  • "decision_id_a": "dec123",
  • "decision_id_b": "dec456"
}

Response samples

Content type
application/json
{
  • "a": {
    },
  • "b": {
    },
  • "diff": {
    }
}

Notifications

Subscribe to audit event notifications

In the pursuit of seamless orchestration, this endpoint was envisioned to allow subscribers to receive notifications of audit events. However, this feature is currently unimplemented. For now, it serves as a gentle reminder to use the POST /v1/webhooks/subscriptions endpoint, where audit event types can be specified for notifications. Stay tuned as the HUMAN platform evolves to support more intricate functionalities.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "https://api.haio.run/errors/validation-error",
  • "title": "Validation Failed",
  • "status": 400,
  • "detail": "The request body contains invalid or missing fields",
  • "instance": "/v1/capabilities/match",
  • "errors": [
    ],
  • "remediation": [],
  • "documentation_url": "https://docs.haio.run/errors/validation-error",
  • "request_id": "req_a7b3c9d2e1f4g5h6",
  • "incident_id": "inc_xyz789"
}

Decision Management

Challenge an audit decision

In the dynamic world of AI governance, sometimes decisions need a second look. This endpoint allows organizations to challenge audit decisions, ensuring transparency and accuracy. By leveraging HUMAN's capability graph, users can request further review or clarification, fostering trust in AI interactions.

Request Body schema: application/json
required
challenger_passport_id
string

The Passport ID of the challenger.

reason
string

The reason for the challenge.

narrative
string

Additional narrative or context for the challenge.

requested_action
string

The action the challenger is requesting, such as 'second_review'.

Responses

Request samples

Content type
application/json

An organization requests a second review of an audit decision due to perceived discrepancies.

{
  • "challenger_passport_id": "passport:12345",
  • "reason": "Discrepancy in data interpretation",
  • "narrative": "The decision was based on outdated data.",
  • "requested_action": "second_review"
}

Response samples

Content type
application/json
{
  • "challenge_id": "chal_67890",
  • "provenance_chain_id": "chal_chain_chal_67890",
  • "status": "open"
}

Challenge Management

Update audit challenge status and disposition

In the complex dance of ensuring compliance, this endpoint allows organizations to update the status and disposition of audit challenges. By empowering organizations to mark challenges as resolved or withdrawn, it orchestrates a seamless interaction between human oversight and AI precision, ensuring that the audit trail remains robust and transparent.

Request Body schema: application/json
required
status
required
string
Enum: "resolved" "withdrawn" "under_review"

The new status of the challenge.

disposition
string

A note or decision regarding the challenge.

Responses

Request samples

Content type
application/json

An example showing the resolution of a challenge.

{
  • "status": "resolved",
  • "disposition": "The issue was addressed satisfactorily."
}

Response samples

Content type
application/json
{
  • "challenge_id": "12345",
  • "updated": true
}

Views

Retrieve audit views for an organization

Explore the intricate records of saved audit views within an organization on the HUMAN platform. This endpoint helps administrators track and manage the audit trail of various views, ensuring transparency and accountability in data handling practices.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "created_at",
  • "hasMore": false
}

Create a new audit view

In a world where transparency is paramount, creating personalized audit views empowers organizations to tailor how they monitor their operations. This endpoint allows you to define and save custom views, enriching your insight into the complex dance of human and AI interactions.

Request Body schema: application/json
required
name
required
string

The name of the audit view.

owner_passport_id
required
string

Passport ID of the owner creating this view.

object

Custom configuration for filtering the audit data.

Responses

Request samples

Content type
application/json

An example where the 'acme' organization creates a view to track invoice processing audits.

{
  • "name": "Invoice Processing",
  • "owner_passport_id": "passport:acme:12345",
  • "filter_config": {
    }
}

Response samples

Content type
application/json
{
  • "view_id": "aview:001122334455"
}

Evidence

Create a new evidence bundle

Embark on a journey to safeguard truth with this endpoint, which crafts cryptographic evidence bundles from decision data. Harness the power of provenance tracking to ensure every decision within an organization is both transparent and verifiable.

Request Body schema: application/json
required
decision_ids
required
Array of strings

List of decision IDs to include in the bundle.

format
string

The format of the evidence bundle, defaulting to 'ops'.

generated_by
string

The DID of the entity generating the bundle. Defaults to the organization DID if not provided.

Responses

Request samples

Content type
application/json

An example of creating an evidence bundle with specified decision IDs.

{
  • "decision_ids": [
    ],
  • "format": "ops",
  • "generated_by": "did:example:generator"
}

Response samples

Content type
application/json
null

Retrieve evidence linked to a Passport

Delve into the rich tapestry of evidence associated with a given Passport. This endpoint empowers you to explore and filter evidence by class, strength, state, and outcome — revealing the provenance behind decisions and interactions within the HUMAN network.

Responses

Response samples

Content type
application/json

A list of evidence items for a specific Passport.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "id",
  • "hasMore": false
}

Batch submit evidence for processing

Harness the collective power of data by submitting multiple evidence items in one go. This endpoint enables organizations to efficiently process evidence with AI-assured safety, ensuring each piece meets consent requirements and tracks its provenance.

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json

Batch of evidence items submitted by Acme Corp for processing.

{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Retrieve Evidence Portfolio by Passport

Uncover the rich tapestry of skills and experiences associated with a cryptographic identity. This endpoint is your gateway to accessing a consolidated view of an individual's capabilities, woven together from their unique Passport DID.

Responses

Response samples

Content type
application/json

Portfolio showcasing skills and evidence for Acme Corporation's agent.

{
  • "portfolio": {
    }
}

Claim Pending Evidence

Securely claim pending evidence using your cryptographic identity (Passport). This endpoint ensures evidence can only be claimed by the rightful owner, with anti-fraud measures to prevent misuse.

Responses

Response samples

Content type
application/json
{
  • "evidence_record": {
    },
  • "claimed": true
}

Disclose fields from evidence record

Reveal specific fields from an evidence record, allowing verifiable claims to be shared securely. This endpoint ensures that only authorized users can disclose fields, maintaining the integrity of the evidence while facilitating trusted interactions.

Request Body schema: application/json
required
disclosed_fields
required
Array of strings

List of fields to disclose.

purpose
string

Purpose of the disclosure.

requester_did
string

DID of the entity requesting disclosure.

Responses

Request samples

Content type
application/json

Request to disclose specific fields for verification purposes.

{
  • "disclosed_fields": [
    ],
  • "purpose": "Verification of identity",
  • "requester_did": "did:example:requester123"
}

Response samples

Content type
application/json
{
  • "verifiable_presentation": {
    },
  • "verifier_challenge": "SGVsbG9Xb3JsZA==",
  • "disclosed_fields": [
    ],
  • "issuer_did": "did:example:issuer456",
  • "evidence_record_id": "record789",
  • "purpose": "Verification of identity",
  • "requester_did": "did:example:requester123"
}

Retrieve detailed evidence record

This endpoint unveils the story behind an evidence record by fetching its details and lifecycle events. It plays a crucial role in understanding the provenance and integrity of an evidence item, ensuring transparency and accountability within the HUMAN platform.

Responses

Response samples

Content type
application/json

Example of a successful retrieval of an evidence record for an invoice processing task.

{
  • "evidence_record": {
    },
  • "evidence_lifecycle_events": [
    ]
}

Challenge Evidence with Conflict Detection

Initiate a challenge against a piece of evidence, flagging it for neutral review if an organizational conflict exists. This endpoint orchestrates the challenge, ensuring fairness and transparency in evidence handling by involving neutral parties when necessary.

Responses

Response samples

Content type
application/json
{
  • "evidence_id": "12345",
  • "status": "challenged",
  • "review_task_created": true,
  • "conflict_detected": true,
  • "adjudicator_role": "compliance_reviewer"
}

Submit verifiable credential evidence

This endpoint empowers organizations to submit evidence of capabilities through verifiable credentials, establishing trust in a world where humans and AI collaborate seamlessly. It ensures that each capability is backed by cryptographic proof, enhancing the trustworthiness of skill attestations.

Request Body schema: application/json
required
passport_did
required
string

The decentralized identifier for the passport, serving as the canonical identity.

credential_id
required
string

The unique identifier of the verifiable credential being submitted.

required
Array of objects

An array of capabilities being attested, each with an optional attestation level.

Responses

Request samples

Content type
application/json

An organization 'acme' submits a credential that attests to an employee's skills in data analysis and project management.

{
  • "passport_did": "did:example:123456789abcdefghi",
  • "credential_id": "cred-123456",
  • "capabilities_attested": [
    ]
}

Response samples

Content type
application/json
{
  • "evidence_id": "cgcr-987654",
  • "status": "accepted",
  • "verification_status": "verified",
  • "passport_did": "did:example:123456789abcdefghi",
  • "credential_id": "cred-123456",
  • "capabilities_updated": [
    ],
  • "recorded_at": "2023-10-11T12:34:56Z"
}

Resolve evidence challenge outcome

This endpoint empowers administrators to decisively resolve challenges against evidence entries. By either dismissing or upholding the evidence challenge, it ensures integrity and trust in the Human-AI orchestration process.

Request Body schema: application/json
required
decision
required
string
Enum: "dismiss" "uphold"

The decision to either 'dismiss' (restore evidence) or 'uphold' (revoke evidence).

Responses

Request samples

Content type
application/json

A decision to dismiss the challenge, restoring the evidence to its verified state.

{
  • "decision": "dismiss"
}

Response samples

Content type
application/json
null

Workbench

Retrieve audit templates for user

Uncover a treasure trove of audit workbench templates tailored for a specific user within an organization. This endpoint empowers organizations to seamlessly track and manage their audit templates, ensuring efficiency and compliance through precise task orchestration.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 10,
  • "cursorField": "createdAt",
  • "hasMore": true
}

Control

Revoke an Audit Grant by ID

In the realm of audit management, control is paramount. This endpoint allows administrators to revoke an existing audit grant, ensuring that outdated or erroneous permissions are swiftly nullified. By invoking this, you secure the integrity of your audit processes when certain grants are no longer valid or necessary.

Responses

Response samples

Content type
application/json

This example shows a grant that was already revoked.

{
  • "grant_id": "123abc",
  • "revoked": false,
  • "already_revoked": true,
  • "revoked_at": "2023-01-15T08:30:00Z"
}

Intent Management

Create and route a new intent

This endpoint breathes life into your HUMAN platform by capturing and shaping user intents for task orchestration. With a blend of AI and human oversight, it transforms raw inputs into actionable intents, ensuring each task is routed with precision and safety.

Request Body schema: application/json
required
raw_input
required
string

The unprocessed text representing the user's intent

source_surface
string
Enum: "companion" "control_plane" "workflow_designer" "agent_builder"

The interface from which the intent originated

modality
string
Enum: "text" "voice" "image" "document" "form" "mixed" "template"

The format of the input data

template_id
string

Optional ID for a specific template if applicable

Responses

Request samples

Content type
application/json

Illustrates a basic text intent submitted from the control plane interface.

{
  • "raw_input": "Process the latest invoices for approval",
  • "source_surface": "control_plane",
  • "modality": "text",
  • "template_id": "invoice-template-001"
}

Response samples

Content type
application/json
{
  • "intent_id": "intent-123456",
  • "status": "routing_in_progress"
}

Update an existing intent brief

Refine and evolve your organization's strategic intents with precision. This endpoint allows you to update specific details of an existing intent brief, ensuring that your plans remain aligned with the latest insights and operational changes.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json

An example showing an update to the title and desired outcome of an intent brief.

{
  • "brief": {
    }
}

Response samples

Content type
application/json

Response showing the updated intent brief details and compilation requirement.

{
  • "brief": {
    },
  • "recompile_required": true
}

Refine an intent's shape and details

This endpoint orchestrates the refinement of an intent, ensuring it aligns with the latest organizational goals and AI safety protocols. By updating an intent's shape, HUMAN ensures that AI-driven tasks remain relevant and precise, guiding both machines and their human counterparts toward success.

Request Body schema: application/json
required
utterance
required
string

A user-provided follow-up statement to further clarify or refine the intent.

Responses

Request samples

Content type
application/json

Refining the intent with a user's additional input for better task accuracy.

{
  • "utterance": "Please ensure this invoice is processed with priority."
}

Response samples

Content type
application/json
null

Compile AI task intent brief

This endpoint transforms a raw intent brief into an actionable resolution plan. It orchestrates AI capabilities to meet organizational needs, ensuring each intent is feasible and compliant. Imagine a team at 'acme' orchestrating invoice approvals with AI precision and human oversight.

Request Body schema: application/json
required
override_capability_ids
Array of strings <capability://> [ items <capability:// > ]

Responses

Request samples

Content type
application/json

Overrides default capabilities with specified ones for a custom AI task resolution.

{
  • "override_capability_ids": [
    ]
}

Response samples

Content type
application/json

Compilation of an intent brief into a resolution plan for invoice processing.

{
  • "resolution_plan": {
    },
  • "brief_id": "intent123"
}

Retrieve Intent Activity

Explore the vibrant tapestry of activities within your organization, dynamically orchestrating human-AI interactions. This endpoint exists to empower administrators by providing a window into the AI intent landscape, allowing for data-driven insights and strategic decision-making.

Responses

Response samples

Content type
application/json

Retrieving the first page of intent activities for the 'acme' organization.

{
  • "data": [
    ],
  • "limit": 10,
  • "cursorFields": [
    ],
  • "hasMore": false
}

Intents

Transcribe audio into intent brief

Transform spoken words into actionable intent briefs, enabling seamless AI orchestration. This endpoint captures and decodes audio snippets, creating structured insights that drive workflow automation.

Request Body schema: application/json
required
audio_base64
string

Base64-encoded audio file to be transcribed.

transcript
string

Optional pre-existing transcription of the audio.

source_surface
string
Enum: "companion" "control_plane" "workflow_designer" "agent_builder"

Origin surface where the request was made.

Responses

Request samples

Content type
application/json

Demonstrating transcription of a Base64 audio input captured from companion surface.

{
  • "audio_base64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA... (truncated)",
  • "source_surface": "companion"
}

Response samples

Content type
application/json
{
  • "brief": {
    },
  • "needs_clarification": false,
  • "clarification_questions": [ ]
}

Provision an Intent Capability Plan

Embark on the journey of orchestrating human and AI collaboration by provisioning an intent capability plan. This endpoint transforms a compiled intent into actionable tasks, ensuring safety and alignment with your organization's unique skills and permissions.

Request Body schema: application/json
required
selected_path_label
required
string

The label of the capability path selected for provisioning.

Responses

Request samples

Content type
application/json

Provisions the capability plan using a specified path label.

{
  • "selected_path_label": "fast-track-integration"
}

Response samples

Content type
application/json
{
  • "provisioning_request": {
    }
}

Intent Extraction

Extract Intent from Document Text

Uncover the essence hidden within your documents by extracting intents with precision. This endpoint transforms raw text into actionable insights, seamlessly integrating human expertise with AI efficiency for enriched task management.

Request Body schema: application/json
required
document_text
required
string

The text content from which to extract intent.

source_surface
string
Enum: "companion" "control_plane" "workflow_designer" "agent_builder"

The interface source where the document text is found.

Responses

Request samples

Content type
application/json

Extracting intent from a document sourced from the control plane.

{
  • "document_text": "Please process the invoice for Acme Corp.",
  • "source_surface": "control_plane"
}

Response samples

Content type
application/json

The extraction process successfully interpreted the document's intent.

{
  • "brief": {
    },
  • "needs_clarification": false,
  • "clarification_questions": [ ]
}

Document Processing

Extract Intent from Document Text

Uncover the essence hidden within your documents by extracting intents with precision. This endpoint transforms raw text into actionable insights, seamlessly integrating human expertise with AI efficiency for enriched task management.

Request Body schema: application/json
required
document_text
required
string

The text content from which to extract intent.

source_surface
string
Enum: "companion" "control_plane" "workflow_designer" "agent_builder"

The interface source where the document text is found.

Responses

Request samples

Content type
application/json

Extracting intent from a document sourced from the control plane.

{
  • "document_text": "Please process the invoice for Acme Corp.",
  • "source_surface": "control_plane"
}

Response samples

Content type
application/json

The extraction process successfully interpreted the document's intent.

{
  • "brief": {
    },
  • "needs_clarification": false,
  • "clarification_questions": [ ]
}

Multimodal

Ingest multimodal intent data

This endpoint allows organizations to seamlessly ingest diverse forms of intent data—be it text, documents, or audio. By processing multimodal inputs, HUMAN enhances the efficiency of task orchestration and ensures that AI models are trained with the richest possible datasets.

Request Body schema: application/json
required
One of
text
required
string

The raw text of the intent.

document_text
string

A textual document representing the intent.

audio_base64
string

Base64-encoded audio data.

source_surface
string
Enum: "companion" "control_plane" "workflow_designer" "agent_builder"

The origin of the intent submission.

Responses

Request samples

Content type
application/json

Submitting a simple text intent from the companion surface.

{
  • "text": "How to process invoices more efficiently?",
  • "source_surface": "companion"
}

Response samples

Content type
application/json
{
  • "brief": {
    },
  • "needs_clarification": false,
  • "clarification_questions": [ ]
}

Lineage

Retrieve intent lineage details for analysis

Uncover the historical context and evolution of a specific intent within the HUMAN platform. This endpoint provides a comprehensive lineage, detailing its versions, associated resolution plans, and related artifacts. This insight is crucial for organizations aiming to audit or enhance their Human-AI orchestration strategies.

Responses

Response samples

Content type
application/json

Fetching the lineage for an intent used in Acme Corp's invoice processing.

{
  • "intent_brief": {
    },
  • "versions": [
    ],
  • "resolution_plan": {
    },
  • "scaffolded_artifacts": [
    ],
  • "execution_runs": [ ],
  • "approvals": [ ],
  • "audit_event_ids": [
    ]
}

Strategic Planning

Update an existing intent brief

Refine and evolve your organization's strategic intents with precision. This endpoint allows you to update specific details of an existing intent brief, ensuring that your plans remain aligned with the latest insights and operational changes.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json

An example showing an update to the title and desired outcome of an intent brief.

{
  • "brief": {
    }
}

Response samples

Content type
application/json

Response showing the updated intent brief details and compilation requirement.

{
  • "brief": {
    },
  • "recompile_required": true
}

Human-AI Orchestration

Refine an intent's shape and details

This endpoint orchestrates the refinement of an intent, ensuring it aligns with the latest organizational goals and AI safety protocols. By updating an intent's shape, HUMAN ensures that AI-driven tasks remain relevant and precise, guiding both machines and their human counterparts toward success.

Request Body schema: application/json
required
utterance
required
string

A user-provided follow-up statement to further clarify or refine the intent.

Responses

Request samples

Content type
application/json

Refining the intent with a user's additional input for better task accuracy.

{
  • "utterance": "Please ensure this invoice is processed with priority."
}

Response samples

Content type
application/json
null

Submit evidence for human-AI interactions

This endpoint allows you to submit evidence related to human-AI interactions, ensuring all interactions are ethically documented and traceable. By importing evidence, you maintain a transparent and accountable system where every decision can be reviewed and audited.

Request Body schema: application/json
required
consent_basis
required
string

The legal basis for consent to process this evidence.

target_passport_did
string

Decentralized Identifier of the human subject related to the evidence.

evidence_details
object

Detailed information about the evidence being submitted.

Responses

Request samples

Content type
application/json

An example showing how to submit evidence for an AI processing an invoice.

{
  • "consent_basis": "consent",
  • "target_passport_did": "did:human:1234abcd",
  • "evidence_details": {
    }
}

Response samples

Content type
application/json

An example of a successful evidence submission.

{
  • "evidence_record": {
    }
}

Provisioning

Provision an Intent Capability Plan

Embark on the journey of orchestrating human and AI collaboration by provisioning an intent capability plan. This endpoint transforms a compiled intent into actionable tasks, ensuring safety and alignment with your organization's unique skills and permissions.

Request Body schema: application/json
required
selected_path_label
required
string

The label of the capability path selected for provisioning.

Responses

Request samples

Content type
application/json

Provisions the capability plan using a specified path label.

{
  • "selected_path_label": "fast-track-integration"
}

Response samples

Content type
application/json
{
  • "provisioning_request": {
    }
}

Scaffold

Generate an Intent Scaffold

This endpoint breathes life into raw intent by transforming it into a scaffold. By orchestrating organizational capabilities and aligning them with intent, it ensures a seamless path from concept to execution. It's where ideas meet structured implementation.

Request Body schema: application/json
required
override_capability_ids
Array of strings <uri> [ items <uri > ]

A list of capability URIs to override the default selection.

Responses

Request samples

Content type
application/json

Overrides default capabilities with specified URIs.

{
  • "override_capability_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "scaffold": {
    }
}

Simulation

Simulate intent execution for analysis

Dive into the future with intent simulations, allowing organizations to preview the outcomes of their strategies before they are executed. This endpoint exists to empower decision-makers, providing them insight and foresight by simulating complex scenarios using the HUMAN platform's orchestration capabilities.

Responses

Response samples

Content type
application/json

Simulates a strategy for the 'acme' organization to process invoices, projecting high success.

{
  • "simulation": {
    }
}

Evidence Management

Submit evidence for human-AI interactions

This endpoint allows you to submit evidence related to human-AI interactions, ensuring all interactions are ethically documented and traceable. By importing evidence, you maintain a transparent and accountable system where every decision can be reviewed and audited.

Request Body schema: application/json
required
consent_basis
required
string

The legal basis for consent to process this evidence.

target_passport_did
string

Decentralized Identifier of the human subject related to the evidence.

evidence_details
object

Detailed information about the evidence being submitted.

Responses

Request samples

Content type
application/json

An example showing how to submit evidence for an AI processing an invoice.

{
  • "consent_basis": "consent",
  • "target_passport_did": "did:human:1234abcd",
  • "evidence_details": {
    }
}

Response samples

Content type
application/json

An example of a successful evidence submission.

{
  • "evidence_record": {
    }
}

Intake new evidence into the system

In the intricate ballet of data and verification, this endpoint serves as the gatekeeper for introducing new evidence into the HUMAN ecosystem. It ensures that each piece of evidence submitted is not only accurately captured but also aligns with the necessary consent protocols, safeguarding both the integrity and privacy of the entities involved.

Request Body schema: application/json
required
intake_event_id
required
string

Unique identifier for the intake event.

schema_version
required
string

Version of the schema used for this intake.

consent_basis
required
string

Legal basis for data consent.

Responses

Request samples

Content type
application/json

A typical request to intake evidence with all necessary fields filled.

{
  • "intake_event_id": "evt_123456789",
  • "schema_version": "1.0.0",
  • "consent_basis": "informed_consent"
}

Response samples

Content type
application/json
{
  • "evidence_record": {
    },
  • "created": true
}

BatchProcessing

Batch submit evidence for processing

Harness the collective power of data by submitting multiple evidence items in one go. This endpoint enables organizations to efficiently process evidence with AI-assured safety, ensuring each piece meets consent requirements and tracks its provenance.

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json

Batch of evidence items submitted by Acme Corp for processing.

{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Data Integrity

Intake new evidence into the system

In the intricate ballet of data and verification, this endpoint serves as the gatekeeper for introducing new evidence into the HUMAN ecosystem. It ensures that each piece of evidence submitted is not only accurately captured but also aligns with the necessary consent protocols, safeguarding both the integrity and privacy of the entities involved.

Request Body schema: application/json
required
intake_event_id
required
string

Unique identifier for the intake event.

schema_version
required
string

Version of the schema used for this intake.

consent_basis
required
string

Legal basis for data consent.

Responses

Request samples

Content type
application/json

A typical request to intake evidence with all necessary fields filled.

{
  • "intake_event_id": "evt_123456789",
  • "schema_version": "1.0.0",
  • "consent_basis": "informed_consent"
}

Response samples

Content type
application/json
{
  • "evidence_record": {
    },
  • "created": true
}

Portfolio

Retrieve Evidence Portfolio by Passport

Uncover the rich tapestry of skills and experiences associated with a cryptographic identity. This endpoint is your gateway to accessing a consolidated view of an individual's capabilities, woven together from their unique Passport DID.

Responses

Response samples

Content type
application/json

Portfolio showcasing skills and evidence for Acme Corporation's agent.

{
  • "portfolio": {
    }
}

Eligibility

Retrieve eligibility snapshot for opportunities

In the fast-paced world of human-AI collaboration, understanding your eligibility for various opportunities is crucial. This endpoint allows users to fetch the latest eligibility snapshot for a given opportunity type based on their cryptographic identity, ensuring informed decision-making and efficient task allocation.

Responses

Response samples

Content type
application/json

Shows eligibility status for a workforce task based on the latest snapshot.

{
  • "passport_did": "did:human:acme-john-doe",
  • "opportunity_type": "workforce_task",
  • "eligibility_status": "eligible",
  • "computed_at": "2023-10-01T12:34:56Z"
}

Refresh Eligibility Evidence Snapshot

In the dynamic world of Human-AI collaboration, it's crucial to ensure that opportunities are matched with the right skills at the right time. This endpoint recalculates the eligibility evidence for a specific opportunity type, ensuring that your HUMAN Passport reflects the most current skill-to-task alignment and readiness for new challenges.

Request Body schema: application/json
required
passport_did
required
string

The Decentralized Identifier (DID) of the HUMAN Passport.

opportunity_type
string
Default: "workforce_task"

The type of opportunity for which to refresh eligibility.

Responses

Request samples

Content type
application/json

Recomputing eligibility for a workforce task using a specific passport DID.

{
  • "passport_did": "did:human:123456789abcdefghi",
  • "opportunity_type": "workforce_task"
}

Response samples

Content type
application/json
{
  • "passport_did": "did:human:123456789abcdefghi",
  • "opportunity_type": "workforce_task",
  • "computed_at": "2023-10-05T14:48:00.000Z",
  • "eligibility_status": "eligible"
}

IdentityVerification

Verify Disclosed Evidence Presentation

Unveil the truth behind cryptographic evidence by verifying its disclosed claims against a BBS+ anchor. This endpoint safeguards the integrity of digital credentials, ensuring trust and transparency in decentralized identity systems.

Request Body schema: application/json
required
presentation
required
object

BBS+ cryptographic presentation object

verifier_challenge
required
string

Challenge string used by the verifier

Responses

Request samples

Content type
application/json

A complete and valid BBS+ presentation with a verifier challenge

{
  • "presentation": {
    },
  • "verifier_challenge": "random-challenge-string"
}

Response samples

Content type
application/json

The presentation is valid with disclosed fields

{
  • "valid": true,
  • "disclosed_fields": [
    ],
  • "issuer_did": "did:example:123456789abcdefghi",
  • "error": null
}

Challenge

Challenge Evidence with Conflict Detection

Initiate a challenge against a piece of evidence, flagging it for neutral review if an organizational conflict exists. This endpoint orchestrates the challenge, ensuring fairness and transparency in evidence handling by involving neutral parties when necessary.

Responses

Response samples

Content type
application/json
{
  • "evidence_id": "12345",
  • "status": "challenged",
  • "review_task_created": true,
  • "conflict_detected": true,
  • "adjudicator_role": "compliance_reviewer"
}

Inference

Infer capabilities for a digital identity

Harness the power of HUMAN's Capability Graph to dynamically infer the skills associated with a digital identity, identified by its DID. This endpoint empowers organizations to efficiently manage and update the skill sets of their digital agents, ensuring they are always aligned with the latest operational needs.

Request Body schema: application/json
required
org_id
required
string

The organization ID to scope the capability inference.

Responses

Request samples

Content type
application/json

Requesting capability inference for Acme Corp's digital identity.

{
  • "org_id": "acme-corp-123"
}

Response samples

Content type
application/json

The capabilities were inferred successfully for the specified DID.

{
  • "proposals_created": 5,
  • "proposals_updated": 3,
  • "did": "did:human:123456789abcdefghi",
  • "ran_at": "2023-10-25T14:48:00Z"
}

Definitions

Retrieve capability definitions list

Uncover the breadth of skills tracked within the HUMAN ecosystem. This endpoint offers a window into the capabilities that define our dynamic landscape, with filters to cater to your specific interests—be it canonical, organizational, or a blend of both.

Responses

Response samples

Content type
application/json
{
  • "definitions": [
    ],
  • "count": 1
}

HUMAN

Create a new capability definition

Crafting a new capability is like sculpting the future of your organization. This endpoint empowers you to define the skills and tasks your AI can perform, embedding them into the HUMAN ecosystem. Use it to expand your capabilities and push the boundaries of what’s possible.

Request Body schema: application/json
required
id
required
string

A unique identifier for the capability

scope
required
string

The scope of the capability, e.g., 'canonical' or 'custom'

status
required
string

The status of the capability, e.g., 'active' or 'inactive'

Responses

Request samples

Content type
application/json

Creating a custom capability for invoice processing

{
  • "id": "capability_12345",
  • "scope": "custom",
  • "status": "active"
}

Response samples

Content type
application/json
null

Retrieve paginated list of canvases

Explore the dynamic world of your HUMAN canvases with this endpoint. Aimed at bringing forth your creative artifacts, it seamlessly integrates your digital identity with a cryptographic passport, ensuring secure and personalized access. Dive into your collection with ease, supported by cursor-based pagination to traverse large datasets effortlessly.

Responses

Response samples

Content type
application/json

Retrieve the first page of canvases created by the user.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": false,
  • "cursorFields": [
    ]
}

Promotion

Promote a Capability Definition

Elevate an organizational capability to a canonical level, ensuring its availability for broader use across the HUMAN platform. This action requires careful authorization and is recorded for provenance.

Request Body schema: application/json
required
canonicalId
required
string

The canonical ID for the capability to promote

justification
string

Reason for promoting this capability

approvedBy
required
string

Passport DID of the approving authority

Responses

Request samples

Content type
application/json

Promoting an 'Invoice Processing' capability to canonical status for broader ecosystem use.

{
  • "canonicalId": "cap_123456",
  • "justification": "High demand across multiple organizations",
  • "approvedBy": "did:human:1234abcd"
}

Response samples

Content type
application/json
{
  • "org_capability_id": "org_cap_7890",
  • "canonical_capability_id": "cap_123456",
  • "status": "promoted"
}

Capability Management

Safely remove capability definition

This endpoint allows you to delete a capability definition when it is safe to do so. It ensures that no active nodes or grants are referencing the definition, maintaining the integrity of the system. Explore the dynamics of capability management as you streamline your organization's skills graph.

Responses

Response samples

Content type
application/json

A capability definition removed from the system successfully.

{
  • "capability_id": "def456",
  • "deleted": true,
  • "deleted_at": "2023-10-14T08:42:00Z"
}

Search

Search for Capability Grants by Skills

Unleash the potential of your human and AI workforce by discovering capability grants that match specific skills and criteria. This endpoint allows you to find the right skill sets by filtering through various parameters, ensuring you connect with the most suitable capabilities for your needs.

Responses

Response samples

Content type
application/json

Acme Corp is looking for AI capabilities in data processing with a minimum confidence weight.

{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "meta": {
    }
}

Query capabilities with complex filters

This endpoint empowers users to query the HUMAN Capability Graph using intricate filters, enabling the discovery of skill sets that match specific criteria. It provides flexibility for large filter sets, ensuring precision and depth in capability matching.

Request Body schema: application/json
required
required
Array of strings or string

A list of skills or a comma-separated string of skills to filter by.

limit
integer

Maximum number of results to return.

cursor
string

Opaque cursor for paginating results.

min_weight
number

Minimum confidence weight for filtering capabilities.

Array of strings or string

A list or comma-separated string of domains to filter within.

sort
string

Field(s) to sort results by.

experience_years__gte
string

Minimum years of experience for filtering.

Responses

Request samples

Content type
application/json

This example queries capabilities by specifying a list of skills and a domain.

{
  • "skills": [
    ],
  • "min_weight": 0.8,
  • "domains__in": "technology",
  • "limit": 10,
  • "sort": "-weight"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null,
  • "meta": {
    }
}

Delegation-scoped KB search with access control

Embark on a quest through the HUMAN knowledge base, where access is determined by the cryptographic credentials you hold. This endpoint allows users to conduct a full-text search, unveiling documents their delegation token permits, ensuring both security and precision in knowledge retrieval.

query Parameters
q
required
string non-empty
Example: q=capability graph design

Search query string matched against KB document titles, summaries, and content.

limit
integer [ 1 .. 50 ]
Default: 10
Example: limit=20

Maximum number of results to return. Capped at 50 regardless of the value supplied.

classification
string
Enum: "ExternalPartner" "Public"

Override the access ceiling for ExternalPartner-scoped tokens. Tokens that already hold kb:read:internal scope receive Internal access and this parameter is ignored.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 1,
  • "query": "AI ethics",
  • "classification_ceiling": "Public"
}

Training

Submit Capability Training Evidence

This endpoint is a gateway to empower learners by formalizing their educational milestones into recognized capabilities. By submitting evidence of training completion, you unlock new doors for skill acknowledgment within the HUMAN network, propelling your journey of continuous growth.

Request Body schema: application/json
required
passport_did
required
string

The Digital Identity (DID) of the learner's passport.

course_id
required
string

Identifier for the completed course.

completion_date
required
string <date-time>

Date when the course was completed, formatted as ISO 8601.

assessment_score
required
number [ 0 .. 1 ]

Score reflecting learner's performance, ranging from 0 to 1.

required
Array of objects

List of capabilities acquired from the course.

Responses

Request samples

Content type
application/json

A complete request showing how a learner's training completion can be submitted.

{
  • "passport_did": "did:human:123456789abcdefghi",
  • "course_id": "course-2023-xyz",
  • "completion_date": "2023-10-15T10:00:00Z",
  • "assessment_score": 0.85,
  • "capabilities_learned": [
    ]
}

Response samples

Content type
application/json
{
  • "evidence_id": "cgtr-20231015100000",
  • "status": "accepted",
  • "passport_did": "did:human:123456789abcdefghi",
  • "course_id": "course-2023-xyz",
  • "completion_date": "2023-10-15T10:00:00Z",
  • "assessment_score": 0.85,
  • "capabilities_updated": [
    ],
  • "recorded_at": "2023-10-15T10:05:00Z"
}

Evidence Submission

Record evidence for capability grant

Submit evidence to validate a capability grant in the HUMAN ecosystem. This endpoint empowers organizations to substantiate their skill claims with trusted data, ensuring integrity in a collaborative workflow.

Request Body schema: application/json
required
passport_did
required
string

The decentralized identifier (DID) of the passport.

capability_id
required
string

Identifier of the capability being evidenced.

required
object

Responses

Request samples

Content type
application/json

Submits evidence for a skill grant with manual verification.

{
  • "passport_did": "did:human:123456789abcdefghi",
  • "capability_id": "capability://acme/coding",
  • "evidence": {}
}

Response samples

Content type
application/json
{
  • "grant_id": "cgev_987654321abcdefghi",
  • "passport_did": "did:human:123456789abcdefghi",
  • "capability_id": "capability://acme/coding",
  • "status": "active",
  • "recorded_at": "2023-10-12T07:20:50.52Z"
}

Recommendations

Retrieve skill growth recommendations

Unlock the potential of your digital identity by exploring tailored skill pathways. This endpoint guides you through suggested capabilities based on your current skill set, helping you navigate the ever-evolving landscape of human and AI symbiosis.

Responses

Response samples

Content type
application/json

Acme Corp employee with DID 'did:human:1234' receives skill recommendations to enhance their digital toolkit.

{
  • "did": "did:human:1234",
  • "recommendations": [
    ]
}

CapabilityGraph

Retrieve Capability Graph Analysts

Dive into the realm of HUMAN's Capability Graph and discover the analysts who orchestrate skills with unmatched precision. This endpoint illuminates the human talents that partner with AI to seamlessly integrate capabilities across the platform, ensuring tasks are expertly routed and executed.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Retrieve Capability Explanation

This endpoint unveils the hidden potential within a specific capability by providing a detailed explanation. It's the key to understanding how a capability ties into an individual's skill set, enabling more strategic task routing and efficient skill utilization within the HUMAN platform.

Responses

Response samples

Content type
application/json

An explanation for the capability associated with a specific Passport.

{
  • "capabilityId": "capability://12345",
  • "explanation": {
    },
  • "linkedSkills": [
    ]
}

Analysts

Retrieve Capability Graph Analysts

Dive into the realm of HUMAN's Capability Graph and discover the analysts who orchestrate skills with unmatched precision. This endpoint illuminates the human talents that partner with AI to seamlessly integrate capabilities across the platform, ensuring tasks are expertly routed and executed.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Global

Submit cross-border capability evidence

In the interconnected world of HUMAN, demonstrating skills across borders is crucial. This endpoint allows agents to submit evidence of their capabilities, verified internationally, to enhance their global reputation and unlock new opportunities. It's about breaking barriers and building a universal profile.

Request Body schema: application/json
required
agentId
required
string

Unique identifier for the agent submitting evidence

evidenceType
required
string
Enum: "certification" "work-sample" "testimonial"

Type of evidence being submitted

required
object

Detailed data of the evidence

Responses

Request samples

Content type
application/json

An agent submits a certification as evidence

{}

Response samples

Content type
application/json
null

Capability

Grant Capability to an Identity

This endpoint empowers identities by granting them specific capabilities, enhancing their skill set within the HUMAN ecosystem. By allowing tailored access, it enables efficient task orchestration and fine-grained control over what each identity can accomplish.

Request Body schema: application/json
required
identityDid
required
string

Decentralized Identifier of the identity receiving the capability.

capabilityUri
required
string <uri>

The URI of the capability being granted.

issuerDid
required
string

Decentralized Identifier of the issuer granting the capability.

Responses

Request samples

Content type
application/json

Grant the 'invoice.processing' capability to an identity.

{
  • "identityDid": "did:human:acme-agent-123",
  • "capabilityUri": "capability://acme/invoice.processing",
  • "issuerDid": "did:human:acme-org-issuer"
}

Response samples

Content type
application/json
{
  • "message": "Capability 'invoice.processing' granted to did:human:acme-agent-123.",
  • "grantId": "grant-xyz-789"
}

Graph

Grant Capability to an Identity

This endpoint empowers identities by granting them specific capabilities, enhancing their skill set within the HUMAN ecosystem. By allowing tailored access, it enables efficient task orchestration and fine-grained control over what each identity can accomplish.

Request Body schema: application/json
required
identityDid
required
string

Decentralized Identifier of the identity receiving the capability.

capabilityUri
required
string <uri>

The URI of the capability being granted.

issuerDid
required
string

Decentralized Identifier of the issuer granting the capability.

Responses

Request samples

Content type
application/json

Grant the 'invoice.processing' capability to an identity.

{
  • "identityDid": "did:human:acme-agent-123",
  • "capabilityUri": "capability://acme/invoice.processing",
  • "issuerDid": "did:human:acme-org-issuer"
}

Response samples

Content type
application/json
{
  • "message": "Capability 'invoice.processing' granted to did:human:acme-agent-123.",
  • "grantId": "grant-xyz-789"
}

Challenge Resolution

Resolve evidence challenge outcome

This endpoint empowers administrators to decisively resolve challenges against evidence entries. By either dismissing or upholding the evidence challenge, it ensures integrity and trust in the Human-AI orchestration process.

Request Body schema: application/json
required
decision
required
string
Enum: "dismiss" "uphold"

The decision to either 'dismiss' (restore evidence) or 'uphold' (revoke evidence).

Responses

Request samples

Content type
application/json

A decision to dismiss the challenge, restoring the evidence to its verified state.

{
  • "decision": "dismiss"
}

Response samples

Content type
application/json
null

AI

Initiate a companion chat session

Engage with the HUMAN platform's companion AI to facilitate seamless conversations. This endpoint is an essential part of creating interactive experiences where AI assists human users by understanding context and responding in real-time. It ensures the AI is informed by past interactions and current context, making it a valuable tool for dynamic user engagement.

Request Body schema: application/json
required
message
required
string

The message to send to the companion AI.

session_id
string

An optional identifier for the chat session to maintain context.

history
Array of strings

Optional array of previous messages for context continuity.

context
object

Additional contextual information to enhance AI understanding.

Responses

Request samples

Content type
application/json

Use this example to initiate a chat while passing previous conversation history and session ID.

{
  • "message": "How do I process invoices?",
  • "session_id": "session-abc123",
  • "history": [
    ],
  • "context": {
    }
}

Response samples

Content type
application/json

An example response where the AI provides guidance on invoice processing.

{
  • "task_id": "task-xyz456",
  • "trace_id": "trace-789xyz",
  • "result": {
    }
}

DocumentRetrieval

Retrieve Knowledge Base Document by ID

Dive into the rich tapestry of knowledge stored within the HUMAN platform. This endpoint allows you to fetch a specific Knowledge Base document, unlocking the power of collective insights. Whether you're an AI seeking guidance or a human exploring new realms, retrieving this document can be your compass.

Responses

Response samples

Content type
application/json

The document about AI safety protocols.

{
  • "id": "kb-123",
  • "title": "Understanding AI Safety",
  • "path": "/docs/ai-safety",
  • "classification": "Public",
  • "governance_tier": "Tier 1",
  • "summary": "An overview of protocols ensuring safe AI deployment.",
  • "content": "The content delves into various AI safety protocols...",
  • "last_updated": "2023-10-12T14:22:00Z"
}

Data Models

Retrieve a Schema by Name

Uncover the intricacies of your data structures by retrieving a specific schema by its name. This endpoint empowers you to understand and validate the data models your HUMAN platform relies on, ensuring seamless integration and operation.

Responses

Response samples

Content type
application/json

Acme Corporation retrieves their invoice schema for validation.

{
  • "name": "invoiceSchema",
  • "schema": {
    }
}

Preferences

Retrieve personalized companion preferences

Unveil a world tailored to your preferences by fetching your companion settings. This endpoint is your gateway to understanding how HUMAN customizes interactions, ensuring a seamless and personal experience orchestrated with AI precision.

Responses

Response samples

Content type
application/json

An example of a user's companion preferences within Acme Corp.

{}

Update Companion Preferences

Tailor your AI companion to your liking by updating its preferences. This endpoint allows you to set the tone, formality, and other attributes of your companion, ensuring it aligns with your personal or organizational style.

Request Body schema: application/json
required
handle
string or null

Unique identifier for the companion

humor_level
string
Enum: "none" "low" "medium" "high"

Humor intensity

formality
string
Enum: "informal" "formal"

Formality level of interactions

verbosity
string
Enum: "concise" "detailed"

Preferred verbosity of responses

domain_context
string or null

Domain-specific context for interactions

custom_instructions
string or null

Custom instructions for the companion

starter_mode
string or null
Enum: "beginner" "intermediate" "advanced"

Starter mode of the companion

onboarding_started_at
string or null <date-time>

Timestamp when onboarding started

onboarding_completed_at
string or null <date-time>

Timestamp when onboarding completed

onboarding_steps_completed
Array of strings

Steps completed in onboarding

first_artifact_delivered
string or null

Timestamp of first artifact delivery

workflow_activations
Array of strings

Activated workflows

academy_opens
Array of strings

Academy opens

reentry_hint_delivered
boolean

Reentry hint status

Responses

Request samples

Content type
application/json

Sets humor to medium and formality to informal for a more casual interaction style.

{
  • "handle": "chatbot123",
  • "humor_level": "medium",
  • "formality": "informal"
}

Response samples

Content type
application/json
{
  • "handle": "chatbot123",
  • "humor_level": "medium",
  • "formality": "informal",
  • "verbosity": "detailed",
  • "domain_context": null,
  • "custom_instructions": null,
  • "starter_mode": "intermediate",
  • "onboarding_started_at": "2023-10-01T12:00:00Z",
  • "onboarding_completed_at": "2023-10-02T12:00:00Z",
  • "onboarding_steps_completed": [
    ],
  • "first_artifact_delivered": "2023-10-03T12:00:00Z",
  • "workflow_activations": [
    ],
  • "academy_opens": [ ],
  • "reentry_hint_delivered": true,
  • "passport_display_name": "John Doe",
  • "avatar_url": "https://example.com/avatar.jpg",
  • "email": "john.doe@example.com",
  • "preferred_language": "en"
}

Remove user preferences by Passport DID

This endpoint allows an organization to wipe user preferences using a Passport DID, ensuring compliance with privacy requests or resets. It's a crucial part of maintaining user autonomy and organizational data integrity.

Responses

Response samples

Content type
application/json

User preferences and signals were successfully cleared for the given Passport DID.

{
  • "ok": true,
  • "target_passport_did": "did:human:123456",
  • "cleared": {
    },
  • "reset_by": "did:human:654321"
}

Retrieve organizational preference defaults

Discover the foundational preferences that guide your organization's operations within the HUMAN platform. This endpoint reveals the default settings, ensuring that your orchestration processes are aligned and consistent. It's crucial for maintaining a seamless integration of AI and human workflows.

Responses

Response samples

Content type
application/json

Example of Acme Corp's default preferences for task routing.

{
  • "org_did": "did:human:org:acme",
  • "preferences": {
    }
}

Update organization default preferences

This endpoint allows organizations to customize their AI companion's interaction style by setting default preferences. Tailor the formality, humor, and verbosity to ensure the AI aligns with your company's culture and communication norms.

Request Body schema: application/json
required
enforce_formality
string or null

The level of formality to enforce.

enforce_humor_off
boolean or null

Whether to enforce humor to be off.

enforce_language
string or null

The language to enforce for communications.

default_formality
string or null

The default formality level for interactions.

default_humor_level
string or null

The default humor level to apply.

default_verbosity
string or null

The default verbosity of responses.

org_instructions
string or null

Custom instructions specific to the organization.

Responses

Request samples

Content type
application/json

This example sets a formal communication style with no humor and English language.

{
  • "enforce_formality": "formal",
  • "enforce_humor_off": true,
  • "enforce_language": "en",
  • "default_formality": "formal",
  • "default_humor_level": null,
  • "default_verbosity": "concise",
  • "org_instructions": "Always use formal greetings."
}

Response samples

Content type
application/json

The response after successfully updating preferences.

{
  • "enforce_formality": "formal",
  • "enforce_humor_off": true,
  • "enforce_language": "en",
  • "default_formality": "formal",
  • "default_humor_level": null,
  • "default_verbosity": "concise",
  • "org_instructions": "Always use formal greetings."
}

Record Turn-Level Conversation Patterns

This endpoint allows the HUMAN Companion agent to observe and record conversational patterns between users and AI assistants, capturing the essence of human-AI interaction. By analyzing these patterns, the system enhances its understanding, enabling more personalized and context-aware responses in future interactions.

Request Body schema: application/json
required
user_text
required
string

The text input by the user.

assistant_text
required
string

The response generated by the AI assistant.

turn_id
string

A unique identifier for the conversation turn.

Responses

Request samples

Content type
application/json

Captures a user's query and assistant's response in a turn.

{
  • "user_text": "What's the weather like today?",
  • "assistant_text": "It's sunny and 75 degrees.",
  • "turn_id": "turn_1698771202931"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "recorded": [
    ]
}

Retrieve pending user preferences

Uncover the hidden preferences waiting to enhance your conversation experience. This endpoint helps users explore personalized settings that have yet to be confirmed, ensuring their interactions are tailored to their unique style. The magic lies in uncovering what your AI companion has learned about your preferences, fostering a more engaging dialogue.

Responses

Response samples

Content type
application/json

Illustrates a typical response with a pending preference suggestion.

{
  • "pending": {
    }
}

Acknowledge companion preferences signal

This endpoint acknowledges a specific signal related to companion preferences, allowing the system to either save or skip the action based on user input. It's a crucial touchpoint for ensuring user preferences are respected in the orchestration of human and AI interactions.

Request Body schema: application/json
required
signal_id
required
string

The unique identifier for the signal.

action
required
string
Enum: "save" "skip"

Action to perform on the signal, either 'save' or 'skip'.

Responses

Request samples

Content type
application/json

An example where the user acknowledges a signal with the 'save' action.

{
  • "signal_id": "abc123",
  • "action": "save"
}

Response samples

Content type
application/json

The response on successfully acknowledging a signal with 'save'.

{
  • "ok": true,
  • "signal": {
    }
}

AI Companion

Remove AI Companion Preferences

Erase your AI Companion's memory to start afresh. This endpoint ensures that explicit preferences, inferred signals, and persistent memories are wiped, giving your AI a clean slate to better serve your evolving needs.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "cleared": {
    }
}

User Preferences

Remove AI Companion Preferences

Erase your AI Companion's memory to start afresh. This endpoint ensures that explicit preferences, inferred signals, and persistent memories are wiped, giving your AI a clean slate to better serve your evolving needs.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "cleared": {
    }
}

Topics

Retrieve curated companion discussion topics

Explore a diverse array of conversation starters designed to enhance interactions between humans and AI. This endpoint empowers users to engage with the HUMAN platform by providing dynamic and contextually relevant topics tailored to their interests. Whether you're a developer or an end-user, these topics help you unlock the full potential of AI interactions, fostering creativity and collaboration.

Responses

Response samples

Content type
application/json

A user retrieves a list of topics for a seamless companion experience.

{
  • "data": [
    ],
  • "limit": 50,
  • "cursorFields": [
    ],
  • "hasMore": true
}

Create or Update Companion Topics

This endpoint allows you to create or update topics associated with a user's companion profile. By harnessing the power of categorization, it enables a richer, more personalized interaction between humans and AI. Elevate your user experience by tailoring interactions based on the topics that matter most.

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json

Adding topics related to a user's interests and preferences.

{
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Chat

Remove a companion chat topic

Effortlessly retire a conversation topic and make room for new ideas in your chat. This endpoint ensures only authorized users can manage topics, preserving the integrity of your discussions.

Responses

Response samples

Content type
application/json

The chat topic with ID 'topic123' was successfully deleted.

{
  • "ok": true,
  • "topic_id": "topic123"
}

Limits

Retrieve billing limits for your organization

Discover the financial boundaries of your organization's AI orchestration with HUMAN. This endpoint reveals your session and daily API rate limits, compute markup, and plan tier caps, helping you manage costs and maximize efficiency. Whether you're a startup on a 'free' plan or an enterprise seeking limitless potential, understanding these limits is crucial for strategic planning.

Responses

Response samples

Content type
application/json
{
  • "mcp_rate_limit_per_session_per_min": 20,
  • "api_rate_limit_per_org_per_day": 100000,
  • "compute_markup_pct": 0,
  • "compute_warning_threshold_pct": 80,
  • "plan_tier_caps": {
    },
  • "org_did": "did:human:acme-org-1234"
}

Canvas

Retrieve paginated list of canvases

Explore the dynamic world of your HUMAN canvases with this endpoint. Aimed at bringing forth your creative artifacts, it seamlessly integrates your digital identity with a cryptographic passport, ensuring secure and personalized access. Dive into your collection with ease, supported by cursor-based pagination to traverse large datasets effortlessly.

Responses

Response samples

Content type
application/json

Retrieve the first page of canvases created by the user.

{
  • "data": [
    ],
  • "limit": 10,
  • "hasMore": false,
  • "cursorFields": [
    ]
}

Create a new canvas for collaboration

This endpoint invites you to orchestrate human and AI interactions by creating a canvas. A canvas is a collaborative space where ideas are transformed into structured insights. It is your creative playground in the HUMAN ecosystem, enabling seamless AI-human collaboration through a robust infrastructure that ensures provenance and identity verification.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json

Creating a canvas for a quarterly business report.

{
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "canvas_id": "abc123",
  • "spec": {
    }
}

Retrieve a specific canvas by ID

Unveil the intricate details of a specific canvas, a dynamic workspace within the HUMAN platform. This endpoint empowers users to access canvases that they are authorized to view, facilitating collaboration and innovation within secure boundaries.

Responses

Response samples

Content type
application/json

This example demonstrates a successful retrieval of an 'acme' organization's invoice processing canvas.

{
  • "spec": {
    }
}

Apply JSON Patch to Canvas with Versioning

This endpoint allows users to apply a JSON Patch to a specific canvas, enabling real-time collaboration and version control. By maintaining a version snapshot, it ensures that all changes are traceable and that users can coordinate seamlessly in dynamic environments.

Request Body schema: application/json
required
required
Array of objects

A non-empty array of JSON Patch operations.

seq
integer

The operation sequence number.

version_label
string

An optional label for the version.

Responses

Request samples

Content type
application/json

Apply a simple patch operation to update canvas title.

{
  • "ops": [
    ],
  • "version_label": "v2.0"
}

Response samples

Content type
application/json
null

Retrieve paginated canvas version history

Explore the rich tapestry of your canvas's evolution with this endpoint. Designed for those who seek to understand the journey of their creations, it provides a paginated list of all versions. Dive deep into the past and see how your ideas have transformed over time.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 2,
  • "hasMore": true,
  • "cursorField": "version"
}

Restore a Previous Canvas Version

In the fast-paced world of collaborative design, moments of inspiration can sometimes be lost. This endpoint allows you to restore a previous version of your canvas, ensuring that no spark of creativity is ever truly extinguished. By leveraging HUMAN's sophisticated provenance tracking, you can effortlessly rewind time and bring back past iterations with ease and transparency.

Responses

Response samples

Content type
application/json
null

Retrieve a specific canvas version

In the ever-evolving world of collaborative design, keeping track of changes is crucial. This endpoint empowers you to fetch a specific version of a canvas, providing a snapshot of its state at a particular moment. Ideal for revisiting past designs or auditing changes.

Responses

Response samples

Content type
application/json

Example of successfully retrieving version 3 of canvas 'abc123'.

{
  • "version_id": "v3-abc123",
  • "canvas_id": "abc123",
  • "version": 3,
  • "version_label": "Initial Design",
  • "spec_snapshot": {
    },
  • "created_at": "2023-10-02T14:48:00Z",
  • "authored_by": "did:human:12345"
}

Collaboration

Create a new canvas for collaboration

This endpoint invites you to orchestrate human and AI interactions by creating a canvas. A canvas is a collaborative space where ideas are transformed into structured insights. It is your creative playground in the HUMAN ecosystem, enabling seamless AI-human collaboration through a robust infrastructure that ensures provenance and identity verification.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json

Creating a canvas for a quarterly business report.

{
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "canvas_id": "abc123",
  • "spec": {
    }
}

Apply JSON Patch to Canvas with Versioning

This endpoint allows users to apply a JSON Patch to a specific canvas, enabling real-time collaboration and version control. By maintaining a version snapshot, it ensures that all changes are traceable and that users can coordinate seamlessly in dynamic environments.

Request Body schema: application/json
required
required
Array of objects

A non-empty array of JSON Patch operations.

seq
integer

The operation sequence number.

version_label
string

An optional label for the version.

Responses

Request samples

Content type
application/json

Apply a simple patch operation to update canvas title.

{
  • "ops": [
    ],
  • "version_label": "v2.0"
}

Response samples

Content type
application/json
null

VersionControl

Restore a Previous Canvas Version

In the fast-paced world of collaborative design, moments of inspiration can sometimes be lost. This endpoint allows you to restore a previous version of your canvas, ensuring that no spark of creativity is ever truly extinguished. By leveraging HUMAN's sophisticated provenance tracking, you can effortlessly rewind time and bring back past iterations with ease and transparency.

Responses

Response samples

Content type
application/json
null

Retrieve a specific canvas version

In the ever-evolving world of collaborative design, keeping track of changes is crucial. This endpoint empowers you to fetch a specific version of a canvas, providing a snapshot of its state at a particular moment. Ideal for revisiting past designs or auditing changes.

Responses

Response samples

Content type
application/json

Example of successfully retrieving version 3 of canvas 'abc123'.

{
  • "version_id": "v3-abc123",
  • "canvas_id": "abc123",
  • "version": 3,
  • "version_label": "Initial Design",
  • "spec_snapshot": {
    },
  • "created_at": "2023-10-02T14:48:00Z",
  • "authored_by": "did:human:12345"
}

User Context

Retrieve User Contexts for Delegated Access

This endpoint reveals the rich tapestry of organizational contexts a human agent operates within. By leveraging delegation, it ensures users can seamlessly access the ecosystems they're part of, empowering decisions with appropriate authority and insight.

Responses

Response samples

Content type
application/json

Retrieve contexts for a user with access to multiple organizations

{
  • "data": [
    ]
}

C2C

Deliver cross-user C2C messages securely

In the interconnected world of HUMAN, delivering messages between users is crucial. This endpoint allows users to send messages directly to another's inbox, ensuring authenticity with Ed25519 signatures. It's the lifeline for secure communication within HUMAN's vibrant ecosystem.

Request Body schema: application/json
required
message_id
required
string

Unique identifier for the message.

thread_id
string

Identifier for the conversation thread.

recipient_did
required
string

DID of the message recipient.

sender_did
required
string

DID of the message sender.

intent_kind
required
string

The type of intent this message carries.

payload
required
object

The actual content of the message.

signature
required
string

Ed25519 signature for message authentication.

created_at
required
string <date-time>

Timestamp when the message was created.

expires_at
string <date-time>

Expiration time of the message, if applicable.

Responses

Request samples

Content type
application/json

A typical message sent from one user to another, ensuring secure delivery.

{
  • "message_id": "msg-123456",
  • "thread_id": "thread-abcde",
  • "recipient_did": "did:example:recipient",
  • "sender_did": "did:example:sender",
  • "intent_kind": "inform",
  • "payload": {
    },
  • "signature": "abc123signature",
  • "created_at": "2023-10-01T14:48:00Z",
  • "expires_at": "2023-10-02T14:48:00Z"
}

Response samples

Content type
application/json
{
  • "received": true,
  • "message_id": "msg-123456"
}

Respond to a C2C message

Orchestrate the dance between humans and AI by responding to a Message using HUMAN's dynamic protocol. Whether accepting, rejecting, or countering, this endpoint ensures the conversation continues with purpose and clarity.

Request Body schema: application/json
required
action
required
string
Enum: "accept" "reject" "counter"

The decision on the message: 'accept', 'reject', or 'counter'.

reason
string

Optional explanation for the chosen action.

Responses

Request samples

Content type
application/json
Example

Shows a response where the user accepts a message with no additional comment.

{
  • "action": "accept"
}

Response samples

Content type
application/json
null

Inbox

Retrieve User's C2C Inbox Messages

Dive into your collaborative journey with the C2C Inbox, where every message is a thread in the fabric of your professional narrative. This endpoint empowers users to access their cross-channel communications, reflecting the dynamic interactions in the HUMAN ecosystem.

Responses

Response samples

Content type
application/json

A user retrieves their inbox messages with a pagination cursor.

{
  • "data": [
    ],
  • "hasMore": false
}

Companions

Search and Rank Companion Directory

Navigate the vast network of Companions in your organization by searching via handle, display name, or role. This endpoint helps you discover and connect with the right agents, ensuring your tasks are matched with the best-suited human or AI Companions.

Responses

Response samples

Content type
application/json

A search for Companions within the 'acme' organization.

{}

Directory

Search and Rank Companion Directory

Navigate the vast network of Companions in your organization by searching via handle, display name, or role. This endpoint helps you discover and connect with the right agents, ensuring your tasks are matched with the best-suited human or AI Companions.

Responses

Response samples

Content type
application/json

A search for Companions within the 'acme' organization.

{}

Retrieve Companion Profile by Handle

Discover a Companion's profile by resolving their unique handle. This endpoint is vital for organizations to seamlessly integrate with their Companions, ensuring smooth operations and collaboration. By connecting with a Companion's profile, organizations can tap into a rich network of skills and capabilities.

Responses

Response samples

Content type
application/json
{
  • "passport_did": "did:human:123456789abcdefghi",
  • "handle": "john_doe",
  • "display_name": "John Doe",
  • "role": "Developer",
  • "avatar_url": "https://avatars.example.com/john_doe.png",
  • "is_active": true,
  • "companion_endpoint": "https://companion.example.com",
  • "public_key": "abc123xyz789",
  • "last_seen_at": "2023-10-01T12:34:56Z",
  • "notification_preferences": {
    }
}

Commands

Retrieve available companion commands

Explore the dynamic world of HUMAN's AI by retrieving a list of commands that your organization can execute. This endpoint empowers you with the knowledge of available operations, enabling seamless integration and orchestration of tasks between humans and AI.

Responses

Response samples

Content type
application/json

A sample response showing the first page of available commands.

{
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "eyJwcyI6IjEyMyIsInEiOiJBTkFMWVpFX0lOVk9JQ0UifQ=="
}

Resolve and execute companion commands

In the intricate dance of Human-AI orchestration, this endpoint serves as the maestro, interpreting and executing commands within the HUMAN ecosystem. It ensures that commands are correctly resolved and executed, enhancing the synergy between human intent and AI capabilities.

Request Body schema: application/json
required
input
required
string

The command input string to be resolved

Responses

Request samples

Content type
application/json

Demonstrates resolving a command using a slash-prefixed format

{
  • "input": "/acme.invoice.process"
}

Response samples

Content type
application/json
null

Proxy

Proxy API requests for Human-AI orchestration

This endpoint acts as a versatile proxy for various Human-AI orchestration tasks. By delegating operations, it empowers users to seamlessly interact with different components of the HUMAN platform, ensuring security and efficiency.

Request Body schema: application/json
required
tool
required
string

The tool to execute, e.g., 'human.passport.get'.

object

Arguments required by the specified tool.

Responses

Request samples

Content type
application/json

An example showing how to retrieve a passport by ID.

{
  • "tool": "human.passport.get",
  • "arguments": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

Subscription Management

Deactivate a Companion Subscription

This endpoint empowers organizations to gracefully deactivate a subscription linked to their Companion. By ensuring subscriptions are only paused when needed, it maintains resource efficiency and security.

Responses

Response samples

Content type
application/json

A successful deactivation of a subscription by the 'acme' organization.

{
  • "subscription_id": "sub_123abc",
  • "status": "inactive"
}