{"openapi":"3.1.0","info":{"title":"Git for Prompts REST API","version":"1.0.0","description":"Local-first prompt package manager and version control for AI engineering. Programmatic access to prompts, versions, and test suites.","contact":{"name":"Karan Wakhare","email":"kwakhare5@gmail.com","url":"https://gitforprompts.vercel.app/contact"},"license":{"name":"MIT","url":"https://github.com/kwakhare5/Git-for-Prompts/blob/main/LICENSE"}},"servers":[{"url":"https://gitforprompts.vercel.app/api/v1","description":"Production Vercel API"}],"security":[{"BearerAuth":[]}],"paths":{"/prompts":{"get":{"summary":"Resolve prompt by name or list prompts","description":"Retrieve prompt repository ID and details by unique name for the authenticated user.","operationId":"listPrompts","parameters":[{"name":"name","in":"query","description":"Unique prompt repository name","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Prompt details and repository ID","content":{"application/json":{"schema":{"type":"object","properties":{"promptId":{"type":"string"},"promptName":{"type":"string"}},"required":["promptId","promptName"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"summary":"Create prompt repository","description":"Initialize a new prompt repository owned by the authenticated key holder.","operationId":"createPrompt","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePromptInput"}}}},"responses":{"201":{"description":"Prompt created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"promptId":{"type":"string"},"promptName":{"type":"string"}},"required":["promptId","promptName"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/prompts/{id}/latest":{"get":{"summary":"Get latest prompt version snapshot","description":"Fetch the latest immutable version snapshot of a prompt repository including system prompt, user template, variables, and model hyperparameter configuration. Supports runtime variable interpolation via query params.","operationId":"getLatestPromptVersion","parameters":[{"name":"id","in":"path","required":true,"description":"Unique prompt repository ID","schema":{"type":"string"}},{"name":"variables","in":"query","style":"deepObject","explode":true,"required":false,"description":"Key-value map of runtime template variables (e.g. ?variables[user_name]=Alice)","schema":{"type":"object","additionalProperties":{"type":"string"}}}],"responses":{"200":{"description":"The latest active prompt version snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LatestPromptVersionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/prompts/{id}/versions":{"post":{"summary":"Push new prompt version","description":"Create and commit an immutable new version snapshot of a prompt. Protected by transactional database locks to prevent sequence collisions.","operationId":"createPromptVersion","parameters":[{"name":"id","in":"path","required":true,"description":"Unique prompt repository ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVersionInput"}}}},"responses":{"201":{"description":"New prompt version snapshot created","content":{"application/json":{"schema":{"type":"object","properties":{"versionId":{"type":"string"},"versionNumber":{"type":"integer"},"variables":{"type":"array","items":{"type":"string"}},"bundle":{"type":["object","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["versionId","versionNumber","variables","createdAt"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Git for Prompts API key (e.g. gfp_live_... or gfp_test_...)"}},"schemas":{"PromptSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"currentVersionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name"]},"LatestPromptVersionResponse":{"type":"object","properties":{"promptId":{"type":"string"},"promptName":{"type":"string"},"versionNumber":{"type":"integer"},"commitMessage":{"type":["string","null"]},"content":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}},"bundle":{"type":["object","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["promptId","promptName","versionNumber","content","variables","createdAt"]},"CreatePromptInput":{"type":"object","properties":{"name":{"type":"string","description":"Unique kebab-case prompt name"},"description":{"type":"string","description":"Optional description of prompt purpose"}},"required":["name"]},"CreateVersionInput":{"type":"object","properties":{"content":{"type":"string","maxLength":100000,"description":"Raw prompt text template"},"commitMessage":{"type":"string","maxLength":500,"description":"Commit message describing prompt changes"},"bundle":{"type":"object","description":"Standardized prompt bundle JSON"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable description of error"},"code":{"type":"string","description":"Machine-readable error classification code"},"hint":{"type":"string","description":"Actionable directive for self-healing AI agents or developers"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Missing, invalid, expired, or revoked Bearer authentication key","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request limit per window"},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in current window"},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"BadRequest":{"description":"Validation failure, missing parameters, or malformed JSON payload","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request limit per window"},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in current window"},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Prompt repository or version not found, or not owned by key holder","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request limit per window"},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in current window"},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"A prompt with this name already exists for the authenticated user","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request limit per window"},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in current window"},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimitExceeded":{"description":"Rate limit threshold exceeded. Standard limit: 60 req/min per IP. Expensive mutation limit: 20 req/min per key.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Maximum requests in window"},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"0 remaining"},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until reset"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds client must wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalError":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}