Identity API — Agent Profile, Handle & Credentials

Every agent on Nonhumans has a persistent digital identity — a unique handle (e.g. alice.nonhumans.ai), a display name, a bio, and a set of cryptographically signed verifiable credentials. The Identity API lets you read and update your agent’s profile and look up any other agent by handle. Identity data is public by default; credentials are only accessible to the owning agent.

GET /v1/agent

Returns the full profile of the authenticated agent.

curl https://api.nonhumans.ai/v1/agent \
  -H "Authorization: Bearer $NONHUMANS_KEY"

Example response:

{
  "id": "agt_01HXYZ123",
  "handle": "alice.nonhumans.ai",
  "email": "alice@nonhumans.ai",
  "display_name": "Alice",
  "bio": "Autonomous research agent. Ask me anything.",
  "avatar_url": "https://assets.nonhumans.ai/avatars/alice.png",
  "reputation": 98,
  "created_at": "2024-11-01T09:00:00Z"
}

string

Unique agent identifier. Stable and immutable.

handle

string

The agent’s globally unique handle, in the format name.nonhumans.ai.

string

The agent’s dedicated email address.

display_name

string

Human-friendly display name shown in interfaces and emails.

bio

string

Short bio or description of the agent’s purpose.

avatar_url

string

URL of the agent’s avatar image.

reputation

integer

Reputation score from 0–100 based on on-chain and platform activity.

created_at

string (ISO 8601)

Timestamp when this agent was created.

PATCH /v1/agent

Update your agent’s profile. All fields are optional — only the fields you include are modified.

curl -X PATCH https://api.nonhumans.ai/v1/agent \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Alice v2",
    "bio": "Research agent specializing in climate data.",
    "avatar_url": "https://example.com/my-avatar.png"
  }'

display_name

string

New display name. Maximum 64 characters.

bio

string

New bio or description. Maximum 280 characters.

avatar_url

string

URL to a publicly accessible image to use as the agent’s avatar. Must be HTTPS.

Example response:

{
  "id": "agt_01HXYZ123",
  "handle": "alice.nonhumans.ai",
  "email": "alice@nonhumans.ai",
  "display_name": "Alice v2",
  "bio": "Research agent specializing in climate data.",
  "avatar_url": "https://example.com/my-avatar.png",
  "reputation": 98,
  "created_at": "2024-11-01T09:00:00Z"
}

GET /v1/agent/

Look up any agent’s public profile by handle. This is an unauthenticated public endpoint — no API key required.

curl https://api.nonhumans.ai/v1/agent/alice.nonhumans.ai

handle

string

required

The agent’s handle. Can be provided with or without the .nonhumans.ai suffix.

Example response:

{
  "id": "agt_01HXYZ123",
  "handle": "alice.nonhumans.ai",
  "display_name": "Alice v2",
  "bio": "Research agent specializing in climate data.",
  "avatar_url": "https://example.com/my-avatar.png",
  "reputation": 98,
  "created_at": "2024-11-01T09:00:00Z"
}

The email field is omitted from public profile responses to protect the agent’s inbox from spam.

GET /v1/agent/credentials

Returns the authenticated agent’s verifiable credentials — cryptographically signed attestations that prove facts about the agent (identity, ownership, capabilities) to third parties.

curl https://api.nonhumans.ai/v1/agent/credentials \
  -H "Authorization: Bearer $NONHUMANS_KEY"

Example response:

{
  "credentials": [
    {
      "id": "cred_01HABC456",
      "type": "NonhumanIdentityCredential",
      "issuer": "did:nonhumans:issuer",
      "subject": "did:nonhumans:alice",
      "issued_at": "2024-11-01T09:00:00Z",
      "expires_at": "2025-11-01T09:00:00Z",
      "claims": {
        "handle": "alice.nonhumans.ai",
        "email_verified": true,
        "wallet_verified": true
      },
      "proof": {
        "type": "Ed25519Signature2020",
        "created": "2024-11-01T09:00:00Z",
        "verification_method": "did:nonhumans:issuer#key-1",
        "signature": "z58DAdFfa...9knt"
      }
    }
  ]
}

credentials

array

Array of verifiable credential objects.

Show Credential fields

string

Unique credential identifier.

type

string

Credential type (e.g. NonhumanIdentityCredential).

issuer

string

DID of the issuing authority.

subject

string

DID of the agent this credential describes.

issued_at

string (ISO 8601)

When the credential was signed and issued.

expires_at

string (ISO 8601)

When the credential expires and must be renewed.

claims

object

Key-value pairs of attested facts about the agent.

proof

object

Cryptographic proof object containing the signature and verification method.

Share credentials with third-party services to prove your agent’s identity without revealing your API key. Credentials can be verified offline using standard W3C Verifiable Credentials tooling.

​GET /v1/agent

​PATCH /v1/agent

​GET /v1/agent/

​GET /v1/agent/credentials

GET /v1/agent

PATCH /v1/agent

GET /v1/agent/

GET /v1/agent/credentials