{"openapi":"3.1.0","info":{"title":"Usama Kelani Portfolio API","version":"1.0.0","description":"Read-only access to published professional content, a fixed integration sandbox, and sanitized public homelab observations. The sole write operation is reserved for the site operator.","contact":{"name":"Usama Kelani","email":"info@usamakelani.com","url":"https://usamakelani.com/contact"}},"servers":[{"url":"https://usamakelani.com","description":"Production public portfolio"}],"externalDocs":{"description":"Authentication, examples, and error handling","url":"https://usamakelani.com/docs"},"tags":[{"name":"Public reads","description":"Unauthenticated public portfolio reads."},{"name":"Operator only","description":"Existing authenticated feed publication; no visitor credentials are issued."}],"security":[],"paths":{"/api":{"get":{"operationId":"discoverPortfolioApi","summary":"Discover public API resources","description":"Start here to find the API version, docs, schema, and public endpoints.","tags":["Public reads"],"security":[],"responses":{"200":{"description":"Published public content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discovery"}}}},"404":{"description":"Resource not found; follow error.hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected failure; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/profile":{"get":{"operationId":"getPortfolioProfile","summary":"Read the professional profile","description":"Returns published contact details, skills, work history, and credential status from the same content as the portfolio. Check updated and credential status before citing.","tags":["Public reads"],"security":[],"responses":{"200":{"description":"Published public content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"}}}},"404":{"description":"Resource not found; follow error.hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected failure; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects":{"get":{"operationId":"listPortfolioProjects","summary":"List selected projects","description":"Returns published project summaries, technologies, and public project links. It does not expose the client products themselves.","tags":["Public reads"],"security":[],"responses":{"200":{"description":"Published public content.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}}}},"404":{"description":"Resource not found; follow error.hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected failure; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/case-studies":{"get":{"operationId":"listEngineeringCaseStudies","summary":"List engineering case studies","description":"Returns identifiers and summaries for all published engineering case studies.","tags":["Public reads"],"security":[],"responses":{"200":{"description":"Published public content.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CaseStudySummary"}}}}},"404":{"description":"Resource not found; follow error.hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected failure; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/case-studies/{slug}":{"get":{"operationId":"getEngineeringCaseStudy","summary":"Read one engineering case study","description":"Returns the published architecture, constraints, validation, results, and review date for the requested study.","tags":["Public reads"],"security":[],"responses":{"200":{"description":"Published public content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseStudy"}}}},"404":{"description":"Resource not found; follow error.hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected failure; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"description":"Stable identifier from the case-study index.","schema":{"type":"string","enum":["ordex","ondemand","learning-hub"]}}]}},"/api/v1/sandbox/profile":{"get":{"operationId":"getSandboxProfile","summary":"Read a fixed sandbox profile","description":"Returns an Example Engineer fixture conforming to Profile. No production write or credential is involved.","tags":["Public reads"],"security":[],"responses":{"200":{"description":"Published public content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"}}}},"404":{"description":"Resource not found; follow error.hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected failure; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/homelab":{"get":{"operationId":"getPublicHomelabObservation","summary":"Read the sanitized public homelab observation","description":"Returns only the latest sanitized observation. Compare generatedAt to the current time; after 90 seconds it is a last snapshot. This operation grants no infrastructure control.","tags":["Public reads"],"security":[],"responses":{"200":{"description":"Published public content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicTelemetry"}}}},"404":{"description":"Resource not found; follow error.hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected failure; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"No observation or temporarily unavailable backend.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":15}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"publishPublicHomelabObservation","summary":"Publish an operator observation","description":"Operator-only publication of an allowlisted observation no larger than 32768 UTF-8 bytes and no older than 90 seconds. The Worker sanitizes it again. A timestamp up to five seconds in the future is tolerated. No key issuance or visitor writes are available.","tags":["Operator only"],"security":[{"OperatorBearer":[]}],"requestBody":{"required":true,"description":"The sanitized public observation, validated again before storage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicTelemetry"}}}},"responses":{"200":{"description":"Observation stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Publication"}}}},"400":{"description":"Malformed or out-of-date observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid operator credential.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Observation older than the stored snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds 32768 bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Feed backend unavailable.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":15}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"hint":{"type":"string","description":"Action to resolve the failure."},"docs":{"type":"string","format":"uri"}},"required":["code","message","hint","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"Discovery":{"type":"object","properties":{"name":{"type":"string","description":"Portfolio API name."},"version":{"type":"string","description":"Semantic API version."},"documentation":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"resources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Resource label."},"url":{"type":"string","format":"uri"}},"required":["name","url"],"additionalProperties":false}}},"required":["name","version","documentation","openapi","resources"],"additionalProperties":false},"Profile":{"type":"object","properties":{"name":{"type":"string","description":"Published name."},"title":{"type":"string","description":"Professional title."},"description":{"type":"string","description":"Published positioning."},"location":{"type":"string","description":"Public region only."},"url":{"type":"string","format":"uri"},"updated":{"type":"string","format":"date"},"contact":{"type":"object","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"Public telephone number."}},"required":["email","phone"],"additionalProperties":false},"links":{"type":"object","properties":{"github":{"type":"string","format":"uri"},"linkedin":{"type":"string","format":"uri"},"itch":{"type":"string","format":"uri"},"resume":{"type":"string","format":"uri"}},"required":["github","linkedin","itch","resume"],"additionalProperties":false},"skills":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string","description":"Skill category."},"skills":{"type":"array","items":{"type":"string"}}},"required":["group","skills"],"additionalProperties":false}},"experience":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","description":"Held role."},"company":{"type":"string","description":"Published employer or client description."},"start":{"type":"string","description":"Start month, YYYY-MM."},"end":{"type":["string","null"],"description":"End month or null for an ongoing role."},"summary":{"type":"string","description":"Published role summary."}},"required":["role","company","start","end","summary"],"additionalProperties":false}},"credentials":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Credential title."},"issuer":{"type":"string","description":"Issuing institution."},"kind":{"type":"string","enum":["degree","cert","program"]},"date":{"type":"string","description":"Published month, YYYY-MM."},"inProgress":{"type":"boolean"},"status":{"type":"string","enum":["planned","in-progress","listed"],"description":"Listed is not an independent verification; follow the verification link when available."},"verificationUrl":{"type":"string","format":"uri"}},"required":["title","issuer","kind","date","inProgress","status"],"additionalProperties":false}}},"required":["name","title","description","location","url","updated","contact","links","skills","experience","credentials"],"additionalProperties":false},"Project":{"type":"object","properties":{"name":{"type":"string","description":"Project name."},"tagline":{"type":"string","description":"Short description."},"description":{"type":"string","description":"Published summary."},"technologies":{"type":"array","items":{"type":"string"}},"url":{"type":"string","format":"uri"}},"required":["name","tagline","description","technologies"],"additionalProperties":false},"CaseStudySummary":{"type":"object","properties":{"slug":{"type":"string","description":"Stable study identifier."},"title":{"type":"string","description":"Study title."},"summary":{"type":"string","description":"Published summary."},"updated":{"type":"string","format":"date"},"url":{"type":"string","format":"uri"}},"required":["slug","title","summary","updated","url"],"additionalProperties":false},"CaseStudy":{"type":"object","properties":{"slug":{"type":"string","description":"Stable study identifier."},"title":{"type":"string","description":"Study title."},"summary":{"type":"string","description":"Published summary."},"role":{"type":"string","description":"Engineering responsibilities."},"status":{"type":"string","description":"Published project status."},"period":{"type":"string","description":"Published time period."},"metrics":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","description":"Published metric including units."},"label":{"type":"string","description":"Metric context and denominator when applicable."}},"required":["value","label"],"additionalProperties":false}},"sections":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Section heading."},"paragraphs":{"type":"array","items":{"type":"string"}},"bullets":{"type":"array","items":{"type":"string"}}},"required":["title"],"additionalProperties":false}},"stack":{"type":"array","items":{"type":"string"}},"updated":{"type":"string","format":"date"},"url":{"type":"string","format":"uri"}},"required":["slug","title","summary","role","status","period","metrics","sections","stack","updated","url"],"additionalProperties":false},"Publication":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"generatedAt":{"type":"number","description":"Observation timestamp in Unix seconds."}},"required":["ok","generatedAt"],"additionalProperties":false},"PublicTelemetry":{"type":"object","properties":{"mode":{"type":"string","enum":["live","degraded","snapshot"]},"generatedAt":{"type":"number","description":"Unix seconds. Data older than 90 seconds is a last snapshot, not current health."},"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Allowlisted public identity."},"name":{"type":"string","description":"Public display name."},"role":{"type":"string","description":"Public role."},"state":{"type":"string","description":"Observed state; not a health guarantee."},"activityState":{"type":"string","description":"Observed activity: working, monitoring, idle, planning, sleeping, paused, stale, unknown, or offline. Online reachability does not imply work."},"status":{"type":"string","description":"Public status."},"activity":{"type":"string","description":"Generic public activity label."},"age":{"type":"string","description":"Public age label; private timing is suppressed."},"ageSeconds":{"type":["number","null"]}},"required":["id","name","role","state","activityState","status","activity","age","ageSeconds"],"additionalProperties":false}},"fleet":{"type":"object","properties":{"counts":{"type":"object","properties":{"ok":{"type":"integer","minimum":0,"description":"Number of passing fleet signals."}},"required":["ok"],"additionalProperties":false},"attention":{"type":"array","items":{"type":"object","properties":{"what":{"type":"string","description":"Generic attention label, without private details."}},"required":["what"],"additionalProperties":false}}},"required":["counts","attention"],"additionalProperties":false},"infrastructure":{"type":"object","properties":{"containers":{"type":"object","properties":{"running":{"type":"integer","minimum":0,"description":"Running containers."},"total":{"type":"integer","minimum":0,"description":"Total containers."},"healthy":{"type":"integer","minimum":0,"description":"Healthy containers."}},"required":["running","total","healthy"],"additionalProperties":false},"services":{"type":"object","properties":{"failed":{"type":"integer","minimum":0,"description":"Failed services."}},"required":["failed"],"additionalProperties":false}},"required":["containers","services"],"additionalProperties":false},"markets":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string","description":"Market symbol."},"label":{"type":"string","description":"Market display name."},"price":{"type":"number","description":"Observed price; research only."},"change":{"type":"number","description":"Observed change."},"currency":{"type":"string","description":"Price currency."},"observedAt":{"type":"number","description":"Unix observation time."},"session":{"type":"string","description":"Market session label."}},"required":["symbol","label","price","change","currency","session"],"additionalProperties":false}},"weather":{"type":"object","properties":{"temperature":{"type":"number","description":"Temperature."},"feelsLike":{"type":"number","description":"Feels-like temperature."},"wind":{"type":"number","description":"Wind reading."},"humidity":{"type":"number","description":"Humidity."},"high":{"type":"number","description":"Forecast high."},"low":{"type":"number","description":"Forecast low."},"sunset":{"type":"string","description":"Sunset label."},"updatedAt":{"type":"number","description":"Unix observation time."},"condition":{"type":"string","description":"Public weather condition."},"city":{"type":"string","description":"Public regional city, not a private address."}},"required":["sunset","condition","city"],"additionalProperties":false},"sentiment":{"type":"object","properties":{"value":{"type":"number","description":"Observed sentiment."},"label":{"type":"string","description":"Sentiment label."},"observedAt":{"type":"number","description":"Unix observation time."}},"required":["label"],"additionalProperties":false},"news":{"type":"array","items":{"type":"object","properties":{"section":{"type":"string","description":"News category."},"title":{"type":"string","description":"Public headline."},"url":{"type":"string","format":"uri"},"source":{"type":"string","description":"News publisher."},"publishedAt":{"type":"number","description":"Unix publication time."}},"required":["section","title","url","source"],"additionalProperties":false}},"feeds":{"type":"object","properties":{"news":{"type":"object","properties":{"updatedAt":{"type":"number","description":"Unix refresh time."}},"required":[],"additionalProperties":false}},"required":["news"],"additionalProperties":false},"collection":{"type":"object","properties":{"sources":{"type":"object","properties":{"agents":{"type":"object","properties":{"state":{"type":"string","enum":["fresh","cached","stale","unavailable"]},"updatedAt":{"type":"number","description":"Agent collector timestamp in Unix seconds; a fresh snapshot cannot renew stale collector evidence."}},"required":["state"],"additionalProperties":false}},"required":["agents"],"additionalProperties":false}},"required":["sources"],"additionalProperties":false}},"required":["mode","generatedAt","agents","fleet","infrastructure","markets","weather","sentiment","news","feeds","collection"],"additionalProperties":false}},"securitySchemes":{"OperatorBearer":{"type":"http","scheme":"bearer","description":"Private site-operator credential, never issued to visitors or included in examples."}}}}