DocsAPI Reference

API Reference

REST API 25 endpoints

Full reference for blueprints, personas, output tracking, and HMAC watermarking. Bearer token authentication. JSON request/response bodies.

Base URLapi.artificial-id.com/v1

Jump to section

Authentication Blueprint Personas Output Tracking Watermarking Rate Limits Code Examples

Authentication

Bearer token auth

All API requests must be authenticated with a Bearer token in the Authorization header. Generate API keys from your dashboard under Settings → API Keys.

Authenticated request

curl https://api.artificial-id.com/v1/blueprint \
  -H "Authorization: Bearer aiid_live_abc123..."

Key format

aiid_live_Production key

aiid_test_Test key (no writes)

Keep your API key secret

API keys are shown only once at creation time. Store them in environment variables — never commit them to source control. If a key is compromised, revoke it immediately from the dashboard and generate a new one.

Blueprint

Blueprint endpoints

GET/v1/blueprint

Fetch the full decrypted blueprint for the authenticated user. Returns all 4 layers and all modules.

Request

curl

curl https://api.artificial-id.com/v1/blueprint \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK · application/json

{
  "id": "bp_01jd8x...",
  "version": 3,
  "layers": { "core_identity": {...}, "voice_tone": {...}, ... }
}

PATCH/v1/blueprint/modules/:id

Update a single module within the blueprint. Only the specified module is re-encrypted and written.

Parameters

idstringModule identifier, e.g. core_identity.communication_style

valueanyNew value for the module. Type must match the module schema.

Request

curl

curl -X PATCH https://api.artificial-id.com/v1/blueprint/modules/voice_tone.formality \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "formal"}'

Response

200 OK · application/json

{
  "module_id": "voice_tone.formality",
  "updated_at": "2026-03-10T14:30:00Z",
  "blueprint_version": 4
}

Personas

Personas endpoints

GET/v1/personas

List all personas for the authenticated user. Each persona is a named, context-specific overlay on the base blueprint.

Request

curl

curl https://api.artificial-id.com/v1/personas \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK · application/json

{
  "personas": [
    { "id": "ps_abc...", "name": "Work Mode", "active": true },
    { "id": "ps_def...", "name": "Open Source", "active": false }
  ],
  "total": 2
}

POST/v1/personas

Create a new persona. Personas inherit all base blueprint modules and override only the fields you specify.

Parameters

namestringHuman-readable label for the persona.

overridesobjectModule overrides. Only specified modules differ from the base.

context_hintstring?Optional note describing when to activate this persona.

Request

curl

curl -X POST https://api.artificial-id.com/v1/personas \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Review Mode",
    "overrides": {
      "voice_tone.verbosity": "detailed",
      "voice_tone.formality": "semi-formal"
    },
    "context_hint": "Use when reviewing PRs or architecture docs"
  }'

Response

200 OK · application/json

{
  "id": "ps_xyz...",
  "name": "Code Review Mode",
  "created_at": "2026-03-10T15:00:00Z"
}

GET/v1/personas/:id

Fetch a single persona with all resolved module values (base blueprint + overrides merged).

Parameters

idstringPersona ID returned from the list or create endpoint.

Request

curl

curl https://api.artificial-id.com/v1/personas/ps_xyz... \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK · application/json

{
  "id": "ps_xyz...",
  "name": "Code Review Mode",
  "resolved": {
    "core_identity": { ... },
    "voice_tone": { "formality": "semi-formal", "verbosity": "detailed", ... },
    ...
  }
}

Output Tracking

Output Tracking endpoints

POST/v1/outputs

Log an AI output that was generated using your blueprint. Used for watermark auditing and usage analytics.

Parameters

contentstringThe generated text to log and optionally sign.

persona_idstring?The persona active when the output was generated.

signboolean?If true, an HMAC-SHA256 watermark signature is attached.

platformstring?Source platform, e.g. "chatgpt", "claude", "cursor".

Request

curl

curl -X POST https://api.artificial-id.com/v1/outputs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Here is my analysis of the PR...",
    "persona_id": "ps_xyz...",
    "sign": true,
    "platform": "cursor"
  }'

Response

200 OK · application/json

{
  "id": "out_01ab...",
  "signature": "hmac-sha256:a3f9...",
  "logged_at": "2026-03-10T16:00:00Z"
}

GET/v1/outputs

List logged outputs. Supports filtering by persona, platform, and date range. Useful for auditing which AI tools have used your blueprint.

Parameters

persona_idstring?Filter by persona.

platformstring?Filter by platform name.

fromISO8601?Start of date range.

toISO8601?End of date range.

limitnumber?Max results (default 50, max 200).

Request

curl

curl "https://api.artificial-id.com/v1/outputs?platform=cursor&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK · application/json

{
  "outputs": [ { "id": "out_01ab...", "platform": "cursor", ... } ],
  "total": 142,
  "page": 1
}

Watermarking

Watermarking endpoints

POST/v1/watermark/sign

Generate an HMAC-SHA256 signature for a piece of content. The signature proves the content was authored using this blueprint.

Parameters

contentstringThe text to sign.

persona_idstring?Persona used during generation (embedded in the signature payload).

Request

curl

curl -X POST https://api.artificial-id.com/v1/watermark/sign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "The solution here is to...", "persona_id": "ps_xyz..."}'

Response

200 OK · application/json

{
  "signature": "hmac-sha256:a3f9c2d1...",
  "signed_at": "2026-03-10T16:01:00Z",
  "ttl_days": 90
}

POST/v1/watermark/verify

Verify that a piece of content matches a previously issued signature. Returns the blueprint owner and persona if valid.

Parameters

contentstringThe original text to verify.

signaturestringThe HMAC-SHA256 signature to check against.

Request

curl

curl -X POST https://api.artificial-id.com/v1/watermark/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The solution here is to...",
    "signature": "hmac-sha256:a3f9c2d1..."
  }'

Response

200 OK · application/json

{
  "valid": true,
  "owner": { "id": "usr_...", "display_name": "Alex Chen" },
  "persona": "Code Review Mode",
  "signed_at": "2026-03-10T16:01:00Z"
}

Rate limits

Usage limits by plan

Limits apply to all endpoints combined. Exceeding the limit returns a 429 response.

Starter

No API access

Markdown export and browser extension only

Pro

10,000 req / month

Rate limit resets on 1st of each month

Enterprise

Unlimited

Dedicated infrastructure, SLA included

Rate limit response headers

X-RateLimit-LimitYour total monthly quota

X-RateLimit-RemainingRequests remaining this period

X-RateLimit-ResetUnix timestamp when the limit resets

Retry-AfterSeconds to wait (only on 429 responses)

Code examples

SDK & library usage

Official SDKs are available for JavaScript/TypeScript and Python. Install with npm i @artificial-id/sdk or pip install artificial-id.

JavaScript / TypeScript

.ts

import { ArtificialId } from '@artificial-id/sdk';

const client = new ArtificialId({
  apiKey: process.env.AIID_API_KEY,
});

// Fetch blueprint
const blueprint = await client.blueprint.get();

// Create a persona
const persona = await client.personas.create({
  name: 'Code Review Mode',
  overrides: {
    'voice_tone.verbosity': 'detailed',
  },
});

// Verify a watermark
const result = await client.watermark.verify({
  content: outputText,
  signature: sigFromDatabase,
});
console.log(result.valid); // true

Python

.py

import artificial_id

client = artificial_id.Client(api_key=os.environ["AIID_API_KEY"])

# Fetch blueprint
blueprint = client.blueprint.get()
print(blueprint.layers.core_identity.name)

# List personas
personas = client.personas.list()
for p in personas:
    print(p.name, p.active)

# Sign an output
signed = client.watermark.sign(
    content="My AI-assisted analysis...",
    persona_id="ps_xyz..."
)
print(signed.signature)

OpenAPI 3.1 specification

Import into Postman, Insomnia, or any OpenAPI-compatible client for auto-generated client code.

openapi.json

Next steps

REST API 25 endpoints

Bearer token auth

Blueprint endpoints

Personas endpoints

Output Tracking endpoints

Watermarking endpoints

Usage limits by plan

SDK & library usage

Related documentation

MCP Server

Security & Encryption

Getting Started