life-my--midst--in

API Reference

Version: 0.2.0
Base URL (Development): http://localhost:3001
Base URL (Production): https://api.inmidstmylife.com

Overview
Authentication
Interactive API Documentation
Core Endpoints
GraphQL API
Error Handling
Rate Limiting

Overview

The In Midst My Life API provides a RESTful interface for managing dynamic, mask-based CVs and résumés. The system supports:

Profile Management: CRUD operations for user profiles with temporal epochs and career stages
Mask System: Context-specific identity masks with cognitive/expressive/operational ontologies
CV Components: Experiences, educations, skills, projects, credentials, and attestations
Narrative Generation: AI-powered résumé narrative blocks with weighting and LLM ranking
Export Formats: JSON-LD (semantic web), PDF (résumé), Verifiable Credentials (W3C standard)
Hunter Protocol: Autonomous job search and application automation
GraphQL API: Unified query interface with subscriptions support

Authentication

Most endpoints require JWT bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Tokens include permission claims for fine-grained access control. Obtain tokens via your authentication provider or identity service.

Unauthenticated Endpoints:

GET /health
GET /ready
GET /openapi.yaml

Interactive API Documentation

Swagger UI

Access interactive API documentation with live testing capabilities:

http://localhost:3001/docs

The Swagger UI provides:

Full endpoint documentation
Request/response schemas
Interactive “Try it out” functionality
Example requests and responses

Redoc

Alternative documentation interface with improved readability:

http://localhost:3001/redoc

Redoc offers:

Clean, responsive layout
Search functionality
Code samples in multiple languages
Downloadable OpenAPI specification

OpenAPI Specification

Download the raw OpenAPI YAML specification:

curl http://localhost:3001/openapi.yaml > openapi.yaml

Two specifications are available:

Main API: /openapi.yaml (Core CV/Mask functionality)
Hunter Protocol: /openapi-hunter.yaml (Job search automation)

Core Endpoints

System

Health Check

GET /health

Returns API health status (always succeeds if server is running).

Response:

{
  "status": "ok"
}

Readiness Probe

GET /ready

Checks if all dependencies (database, cache, etc.) are healthy.

Response (200):

{
  "status": "ready"
}

Response (503):

{
  "status": "degraded",
  "checks": {
    "database": "healthy",
    "cache": "unhealthy"
  }
}

Metrics

GET /metrics

Returns Prometheus-compatible metrics for monitoring.

Response:

# HELP http_requests_total Total HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="GET",route="/profiles",status="200"} 1247
...

⚠️ Security Note: Restrict /metrics endpoint in production via ingress auth or IP allowlist.

Profiles

List Profiles

GET /profiles

Retrieve all profiles for the authenticated user.

Query Parameters:

limit (integer, optional): Maximum number of results (default: 50, max: 100)
offset (integer, optional): Pagination offset (default: 0)

Response:

{
  "profiles": [
    {
      "id": "uuid",
      "slug": "john-doe",
      "displayName": "John Doe",
      "title": "Software Engineer",
      "isActive": true,
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Get Profile

GET /profiles/{id}

Retrieve a specific profile by ID.

Response:

{
  "id": "uuid",
  "identityId": "uuid",
  "slug": "john-doe",
  "displayName": "John Doe",
  "title": "Software Engineer",
  "headline": "Building scalable systems",
  "summaryMarkdown": "Experienced engineer...",
  "avatarUrl": "https://example.com/avatar.jpg",
  "locationText": "San Francisco, CA",
  "isActive": true,
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-15T00:00:00Z"
}

Create Profile

POST /profiles
Content-Type: application/json

Request Body:

{
  "slug": "john-doe",
  "displayName": "John Doe",
  "title": "Software Engineer",
  "headline": "Building scalable systems",
  "summaryMarkdown": "Experienced engineer with 10+ years...",
  "locationText": "San Francisco, CA"
}

Response (201):

{
  "id": "uuid",
  "slug": "john-doe",
  "displayName": "John Doe",
  ...
}

Update Profile

PATCH /profiles/{id}
Content-Type: application/json

Request Body (partial):

{
  "title": "Senior Software Engineer",
  "headline": "Leading distributed systems"
}

Delete Profile

DELETE /profiles/{id}

Soft deletes a profile (sets isActive: false).

Response (204): No content

Select Masks

POST /profiles/{id}/masks/select
Content-Type: application/json

Selects the best masks for a profile based on contexts and tags.

Request Body:

{
  "contexts": ["design", "leadership"],
  "tags": ["impact", "innovation"],
  "limit": 5
}

Response:

{
  "masks": [
    {
      "id": "mask-architect",
      "name": "Architect",
      "ontology": "cognitive-synthesis",
      "relevanceScore": 0.95
    }
  ]
}

Build Narrative

POST /profiles/{id}/narrative
Content-Type: application/json

Generates AI-powered narrative blocks for résumé.

Request Body:

{
  "contexts": ["technical"],
  "tags": ["backend", "distributed-systems"],
  "timeline": [
    {
      "id": "exp-1",
      "title": "Senior Engineer at Acme",
      "start": "2020-01-01",
      "end": "2023-12-31",
      "tags": ["backend", "microservices"]
    }
  ],
  "settings": {
    "tone": "professional",
    "compression_ratio": 0.7
  }
}

Response:

{
  "narrative_blocks": [
    {
      "block_id": "nb-1",
      "text": "Led the architecture and implementation of a microservices platform...",
      "weight": 0.9,
      "sources": ["exp-1"],
      "meta": {
        "personality": "analytical",
        "setting": "professional"
      }
    }
  ]
}

CV Components

Experiences

List Experiences

GET /profiles/{profileId}/experiences

Create Experience

POST /profiles/{profileId}/experiences
Content-Type: application/json

Request Body:

{
  "title": "Senior Software Engineer",
  "company": "Acme Inc",
  "location": "San Francisco, CA",
  "startDate": "2020-01-01",
  "endDate": "2023-12-31",
  "isCurrent": false,
  "description": "Led backend team...",
  "achievements": [
    "Reduced latency by 40%",
    "Migrated to microservices"
  ],
  "technologies": ["Node.js", "PostgreSQL", "Docker"],
  "tags": ["backend", "leadership"]
}

Update/Delete Experience

PATCH /profiles/{profileId}/experiences/{id}
DELETE /profiles/{profileId}/experiences/{id}

Skills

List Skills

GET /profiles/{profileId}/skills

Create Skill

POST /profiles/{profileId}/skills
Content-Type: application/json

Request Body:

{
  "name": "TypeScript",
  "category": "Programming Languages",
  "proficiencyLevel": "expert",
  "yearsOfExperience": 5,
  "tags": ["frontend", "backend"]
}

Projects

List Projects

GET /profiles/{profileId}/projects

Create Project

POST /profiles/{profileId}/projects
Content-Type: application/json

Request Body:

{
  "name": "Open Source CLI Tool",
  "description": "A productivity tool for developers",
  "url": "https://github.com/user/project",
  "startDate": "2024-01-01",
  "status": "active",
  "technologies": ["TypeScript", "Node.js"],
  "tags": ["open-source", "cli"]
}

Masks & Taxonomy

List Masks

GET /masks

Returns predefined identity masks from the taxonomy.

Query Parameters:

ontology (string, optional): Filter by ontology (cognitive/expressive/operational)

Response:

{
  "masks": [
    {
      "id": "analyst",
      "name": "Analyst",
      "ontology": "cognitive-precision",
      "functional_scope": "Precision reasoning and structured analysis",
      "stylistic_parameters": {
        "tone": "formal",
        "rhetorical_mode": "analytical",
        "compression_ratio": 0.6
      }
    }
  ]
}

Get Mask Details

GET /masks/{id}

List Epochs

GET /epochs

Returns temporal epoch definitions (e.g., “Formative”, “Mature”, “Synthesis”).

List Stages

GET /stages

Returns career stage definitions (e.g., “Learning”, “Contributing”, “Leading”).

Exports

Export JSON-LD

GET /profiles/{id}/export/jsonld

Exports profile as semantic web JSON-LD.

Response:

{
  "@context": "https://schema.org/",
  "@type": "Person",
  "name": "John Doe",
  "jobTitle": "Software Engineer",
  "worksFor": [...]
}

Export PDF

GET /profiles/{id}/export/pdf

Generates a formatted résumé PDF.

Query Parameters:

maskId (string, optional): Apply specific mask filter

Response: Binary PDF file

Export Verifiable Credential

GET /profiles/{id}/export/vc

Exports W3C Verifiable Credential bundle.

Response:

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["VerifiableCredential"],
  "issuer": "did:example:123",
  "issuanceDate": "2025-01-17T00:00:00Z",
  "credentialSubject": {...}
}

Hunter Protocol

The Hunter Protocol provides autonomous job search and application automation.

Search Jobs

POST /jobs/search
Content-Type: application/json

Request Body:

{
  "keywords": ["TypeScript", "Senior Engineer"],
  "location": "Remote",
  "profileId": "uuid"
}

Response:

{
  "jobs": [
    {
      "id": "job-1",
      "title": "Senior TypeScript Engineer",
      "company": "Tech Corp",
      "location": "Remote",
      "salaryRange": "$150k-$200k",
      "url": "https://example.com/job",
      "postedAt": "2025-01-15T00:00:00Z"
    }
  ]
}

Analyze Skill Gap

POST /jobs/{jobId}/analyze-gap
Content-Type: application/json

Request Body:

{
  "profileId": "uuid"
}

Response:

{
  "required": ["TypeScript", "React", "PostgreSQL"],
  "present": ["TypeScript", "React"],
  "missing": ["PostgreSQL"],
  "importance": "medium"
}

Tailor Resume

POST /jobs/{jobId}/tailor-resume
Content-Type: application/json

Request Body:

{
  "profileId": "uuid"
}

Response:

{
  "maskId": "architect",
  "maskName": "Architect",
  "highlightedExperiences": ["exp-1", "exp-2"],
  "tailoringSummary": "Emphasized system design experience"
}

Generate Cover Letter

POST /jobs/{jobId}/generate-cover-letter
Content-Type: application/json

Request Body:

{
  "profileId": "uuid",
  "tone": "professional"
}

Response:

{
  "text": "Dear Hiring Manager,\n\nI am excited to apply...",
  "wordCount": 350
}

GraphQL API

Access the unified GraphQL endpoint at /graphql.

Schema Introspection

GET /graphql/schema

Example Query

query GetProfile($id: ID!) {
  profile(id: $id) {
    id
    displayName
    experiences {
      title
      company
      startDate
    }
    masks {
      name
      ontology
    }
  }
}

Subscriptions

subscription OnJobFound($profileId: ID!) {
  jobFound(profileId: $profileId) {
    id
    title
    company
  }
}

Error Handling

All errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  }
}

Common Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Request validation failed
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource already exists
`QUOTA_EXCEEDED`	429	Rate limit or quota exceeded
`INTERNAL_ERROR`	500	Server error

Rate Limiting

Quota-Based Limits (Hunter Protocol)

Feature	FREE	PRO	ENTERPRISE
Job Searches	5/month	Unlimited	Unlimited
Resume Tailoring	0/month	5/month	Unlimited
Cover Letters	0/month	3/month	Unlimited
Auto-Apply	0/month	5/month	Unlimited

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 75
X-RateLimit-Reset: 1642435200

Exceeding Limits

When quota is exceeded, the API returns:

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota exceeded for this feature",
    "details": {
      "feature": "resume_tailoring",
      "limit": 5,
      "used": 5,
      "resetDate": "2025-02-01T00:00:00Z"
    }
  }
}

Performance Benchmarks

API Response Times (p95, local dev):

Profile reads: <120ms
Narrative builds: <300ms
JSON-LD export: <200ms
PDF export: <450ms

Caching:

Taxonomy endpoints (masks/epochs/stages) use Redis-backed caching with in-memory fallback
Cache TTL: 1 hour
Cache invalidation on taxonomy updates

Additional Resources

OpenAPI Specifications: /openapi.yaml, /openapi-hunter.yaml
Swagger UI: /docs
Redoc: /redoc
GraphQL Playground: /graphql
Deployment Guide: DEPLOYMENT.md
Developer Guide: DEVELOPER_GUIDE.md
Hunter Protocol Documentation: HUNTER-PROTOCOL.md

Support

GitHub Issues: https://github.com/anthropics/in-midst-my-life/issues
API Support: padavano.anthony@gmail.com
Documentation: https://github.com/anthropics/in-midst-my-life/docs

This site is open source. Improve this page.

life-my--midst--in

API Reference

Table of Contents

Overview

Authentication

Interactive API Documentation

Swagger UI

Redoc

OpenAPI Specification

Core Endpoints

System

Health Check

Readiness Probe

Metrics

Profiles

List Profiles

Get Profile

Create Profile

Update Profile

Delete Profile

Select Masks

Build Narrative

CV Components

Experiences

List Experiences

Create Experience

Update/Delete Experience

Skills

List Skills

Create Skill

Projects

List Projects

Create Project

Masks & Taxonomy

List Masks

Get Mask Details

List Epochs

List Stages

Exports

Export JSON-LD

Export PDF

Export Verifiable Credential

Hunter Protocol

Search Jobs

Analyze Skill Gap

Tailor Resume

Generate Cover Letter

GraphQL API

Schema Introspection

Example Query

Subscriptions

Error Handling

Common Error Codes

Rate Limiting

Quota-Based Limits (Hunter Protocol)

Rate Limit Headers

Exceeding Limits

Performance Benchmarks

Additional Resources

Support