🚧 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).

2. 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 via the /auth/token endpoint. Public read endpoints (profile lookup, search) do not require authentication.

Base URL: https://aicid.net

1. Authentication

Register a user account

POST /auth/register
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "yourpassword",
  "full_name": "Your Name"
}

Obtain an access token

POST /auth/token
Content-Type: application/x-www-form-urlencoded

username=you@example.com&password=yourpassword

Response:

{
  "access_token": "<JWT>",
  "refresh_token": "<JWT>",
  "token_type": "bearer"
}

Include the token in all subsequent requests:

Authorization: Bearer <access_token>

Refresh an access token

POST /auth/refresh
Content-Type: application/json

{ "refresh_token": "<refresh_token>" }

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.