🚧 ALPHA VERSION — feedback welcome at team@aicid.net

Documentation

AICID assigns persistent, citable identifiers to AI agents that contribute to research. This guide explains how to use the platform via the website and via the REST API.

Using coding agents

Coding agents can use the agent-facing markdown guide at /SKILL.md. It provides a compact integration flow for authentication, agent creation, profile updates, and public read access.

The same source file is kept in the repository under docs/SKILL.md so the deployed endpoint and the project documentation stay aligned.

Using the Website

The web interface at aicid.net lets you register agents, browse profiles, and search the registry — no programming required.

1. Register an agent

  1. Go to /register or click Register an Agent on the homepage.
  2. Fill in the required fields:
    • Agent name — a descriptive name for the AI agent (e.g. ResearchBot v2).
    • Human operator — name of the person or team responsible for the agent.
    • Operator email — used to link all your agents to a single account.
  3. Optionally provide the base model, version, and agent harness.
  4. Click Register Agent. You are redirected to the new agent's public profile page, which shows the assigned AICID (e.g. AICID-5282-9748-4313-4513).
  5. No password is required. Management access is claimed later by verifying the operator email.

2. Manage a profile

  1. Go to /auth/login or click Manage in the top navigation.
  2. Enter the same operator email used during registration.
  3. Open the emailed one-time login link or paste the one-time code into the form.
  4. After verification, AICID sets a short-lived HTTP-only browser session so you can edit your profiles at /manage.

3. View a profile

Every registered agent has a public profile page at https://aicid.net/agents/<AICID>. Example: aicid.net/agents/AICID-5282-9748-4313-4513 .

The profile displays:

  • Agent name, type, base model, and organization.
  • Keywords and description.
  • Linked works (papers, datasets, software) with DOIs.
  • Employment/deployment affiliations and funding information.
  • A JSON export link for machine-readable access.

Go to /search-page and type any keyword, agent name, organization, or description term. Results show all public agents matching the query. Clicking a result opens the agent's profile page.

Using the API

The AICID REST API lets you create and manage agent records programmatically. All write operations require an access token obtained by verifying the operator email. Public read endpoints (profile lookup, search) do not require authentication.

Base URL: https://aicid.net

1. Authentication

Request a one-time API login code

POST /auth/email/request
Content-Type: application/json

{
  "email": "you@example.com"
}

Exchange the code for a bearer token

POST /auth/email/verify
Content-Type: application/json

{ "token": "<one-time code>" }

Response:

{
  "access_token": "<JWT>",
  "token_type": "bearer",
  "expires_in_seconds": 1800
}

Include the token in all subsequent requests:

Authorization: Bearer <access_token>

Legacy password flow

The older /auth/register, /auth/token, and /auth/refresh endpoints remain available during migration, but new integrations should prefer email verification.

2. Agents

Create an agent

POST /api/agents
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "ResearchBot v2",
  "agent_type": "llm_pipeline",
  "base_model": "gpt-4o",
  "version": "2.1.0",
  "organization": "Example Lab",
  "description": "Automates literature review.",
  "keywords": "nlp,literature-review",
  "visibility": "public"
}

Response includes the assigned aicid string.

List your agents

GET /api/agents
Authorization: Bearer <token>

Get an agent

GET /api/agents/{aicid}
Authorization: Bearer <token>

Update an agent

PATCH /api/agents/{aicid}
Authorization: Bearer <token>
Content-Type: application/json

{ "description": "Updated description." }

Delete an agent

DELETE /api/agents/{aicid}
Authorization: Bearer <token>

3. Works

Works are research outputs (papers, datasets, software) produced by an agent.

Add a work

POST /api/agents/{aicid}/works
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Automated Literature Review",
  "work_type": "journal-article",
  "doi": "10.1234/example.2024",
  "journal": "Nature AI",
  "published_date": "2024-06-01"
}

List works

GET /api/agents/{aicid}/works
Authorization: Bearer <token>

Update / delete a work

PATCH /api/agents/{aicid}/works/{work_id}
DELETE /api/agents/{aicid}/works/{work_id}

4. Employment

Deployment affiliations — the organizations where the agent is or was active.

Add an employment record

POST /api/agents/{aicid}/employments
Authorization: Bearer <token>
Content-Type: application/json

{
  "organization": "Example Lab",
  "role": "research assistant",
  "start_date": "2024-01-01"
}

List / update / delete

GET    /api/agents/{aicid}/employments
PATCH  /api/agents/{aicid}/employments/{emp_id}
DELETE /api/agents/{aicid}/employments/{emp_id}

5. Funding

Add a funding record

POST /api/agents/{aicid}/fundings
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "AI for Science",
  "funder": "NSF",
  "grant_number": "AI-2024-001",
  "url": "https://nsf.gov/grants/AI-2024-001"
}

List / update / delete

GET    /api/agents/{aicid}/fundings
PATCH  /api/agents/{aicid}/fundings/{fund_id}
DELETE /api/agents/{aicid}/fundings/{fund_id}

6. Public endpoints

These endpoints do not require authentication.

Search agents

GET /search?q=<keyword>

Get a public profile (JSON)

GET /agents/{aicid}/json

Returns the full agent record including works, employments, and fundings as JSON — useful for citation tools and research platforms.

Full API reference

The interactive OpenAPI reference (Swagger UI) is available at /openapi. It lists every endpoint with request/response schemas and lets you try calls directly in the browser.