C
CommandAGI
Docs/API/Profiles

Profiles API

Create, manage, and query taste profiles. Profiles capture aesthetic preferences through constraints, exemplars, and comparisons.

GET/v1/profiles

List all taste profiles for your projects. Optionally filter by project ID.

Query Parameters

ParameterTypeDescription
projectIdstringOptional. Filter profiles by project
Request
curl https://api.commandAGI.com/v1/profiles \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by project
curl "https://api.commandAGI.com/v1/profiles?projectId=proj_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "profiles": [
    {
      "id": "prof_abc123",
      "projectId": "proj_xyz789",
      "name": "cinematic-look",
      "seed": "Dark, moody cinematography",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:22:00Z"
    }
  ]
}
POST/v1/profiles

Create a new taste profile within a project. The profile starts with an empty main branch.

Request Body

FieldTypeDescription
projectIdstringRequired. The project to create the profile in
namestringRequired. A unique name for the profile
seedstringOptional. Natural language description of the aesthetic
Request
curl -X POST https://api.commandAGI.com/v1/profiles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_abc123",
    "name": "cinematic-look",
    "seed": "Dark, moody cinematography with high contrast"
  }'
Response
{
  "id": "prof_def456",
  "projectId": "proj_abc123",
  "name": "cinematic-look",
  "seed": "Dark, moody cinematography with high contrast",
  "createdAt": "2024-01-15T10:30:00Z"
}
GET/v1/profiles/:id

Retrieve a specific taste profile with all its data, including branches, versions, and the effective snapshot.

Request
curl https://api.commandAGI.com/v1/profiles/prof_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "id": "prof_abc123",
  "projectId": "proj_xyz789",
  "name": "cinematic-look",
  "seed": "Dark, moody cinematography",
  "profileData": {
    "branches": [
      {
        "id": "main",
        "name": "main",
        "description": "Main branch",
        "headVersionId": "v_123",
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "versions": [...],
    "currentBranchId": "main",
    "workingChanges": {
      "constraints": [],
      "exemplars": [],
      "comparisons": []
    },
    "budget": {
      "questions": { "used": 15, "total": 20 },
      "labels": { "used": 42, "total": 50 },
      "comparisons": { "used": 87, "total": 100 }
    }
  },
  "effectiveSnapshot": {
    "constraints": [...],
    "exemplars": [...],
    "comparisons": [...],
    "latentScores": { "frm_1": 0.82, "frm_2": 0.45 },
    "promptSummary": "Cinematic visuals with...",
    "embeddingCentroid": [0.12, -0.34, ...]
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:22:00Z"
}
PATCH/v1/profiles/:id

Update a taste profile's metadata or data. Only provided fields are updated.

Request Body

FieldTypeDescription
namestringOptional. New name for the profile
seedstringOptional. Updated seed description
profileDataobjectOptional. Full profile data structure
effectiveSnapshotobjectOptional. Computed snapshot data
Request
curl -X PATCH https://api.commandAGI.com/v1/profiles/prof_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cinematic-look-v2",
    "seed": "High contrast film noir aesthetic"
  }'
Response
{
  "id": "prof_abc123",
  "projectId": "proj_xyz789",
  "name": "cinematic-look-v2",
  "seed": "High contrast film noir aesthetic",
  "updatedAt": "2024-01-20T15:00:00Z"
}
DELETE/v1/profiles/:id

Permanently delete a taste profile. This action cannot be undone.

Request
curl -X DELETE https://api.commandAGI.com/v1/profiles/prof_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "success": true
}

Related Endpoints

Evaluation API - Score content against profilesExport API - Export profiles for offline use
API ReferenceFrames API