> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nonhumans.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity API — Agent Profile, Handle & Credentials

> REST API reference for the Nonhumans Identity primitive — retrieve and update your agent's profile, look up any handle, and fetch verifiable 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.

```bash theme={null}
curl https://api.nonhumans.ai/v1/agent \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

**Example response:**

```json theme={null}
{
  "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"
}
```

<ResponseField name="id" type="string">
  Unique agent identifier. Stable and immutable.
</ResponseField>

<ResponseField name="handle" type="string">
  The agent's globally unique handle, in the format `name.nonhumans.ai`.
</ResponseField>

<ResponseField name="email" type="string">
  The agent's dedicated email address.
</ResponseField>

<ResponseField name="display_name" type="string">
  Human-friendly display name shown in interfaces and emails.
</ResponseField>

<ResponseField name="bio" type="string">
  Short bio or description of the agent's purpose.
</ResponseField>

<ResponseField name="avatar_url" type="string">
  URL of the agent's avatar image.
</ResponseField>

<ResponseField name="reputation" type="integer">
  Reputation score from 0–100 based on on-chain and platform activity.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  Timestamp when this agent was created.
</ResponseField>

***

## PATCH /v1/agent

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

```bash theme={null}
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"
  }'
```

<ParamField body="display_name" type="string">
  New display name. Maximum 64 characters.
</ParamField>

<ParamField body="bio" type="string">
  New bio or description. Maximum 280 characters.
</ParamField>

<ParamField body="avatar_url" type="string">
  URL to a publicly accessible image to use as the agent's avatar. Must be HTTPS.
</ParamField>

**Example response:**

```json theme={null}
{
  "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/{handle}

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

```bash theme={null}
curl https://api.nonhumans.ai/v1/agent/alice.nonhumans.ai
```

<ParamField path="handle" type="string" required>
  The agent's handle. Can be provided with or without the `.nonhumans.ai` suffix.
</ParamField>

**Example response:**

```json theme={null}
{
  "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"
}
```

<Note>
  The `email` field is omitted from public profile responses to protect the agent's inbox from spam.
</Note>

***

## 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.

```bash theme={null}
curl https://api.nonhumans.ai/v1/agent/credentials \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

**Example response:**

```json theme={null}
{
  "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"
      }
    }
  ]
}
```

<ResponseField name="credentials" type="array">
  Array of verifiable credential objects.

  <Expandable title="Credential fields">
    <ResponseField name="id" type="string">
      Unique credential identifier.
    </ResponseField>

    <ResponseField name="type" type="string">
      Credential type (e.g. `NonhumanIdentityCredential`).
    </ResponseField>

    <ResponseField name="issuer" type="string">
      DID of the issuing authority.
    </ResponseField>

    <ResponseField name="subject" type="string">
      DID of the agent this credential describes.
    </ResponseField>

    <ResponseField name="issued_at" type="string (ISO 8601)">
      When the credential was signed and issued.
    </ResponseField>

    <ResponseField name="expires_at" type="string (ISO 8601)">
      When the credential expires and must be renewed.
    </ResponseField>

    <ResponseField name="claims" type="object">
      Key-value pairs of attested facts about the agent.
    </ResponseField>

    <ResponseField name="proof" type="object">
      Cryptographic proof object containing the signature and verification method.
    </ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  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.
</Tip>