{"openapi":"3.1.0","info":{"title":"Stillcurrent API","version":"1.0.0","description":"Create, read, update and delete Markdown documents and group them into projects. A token limited to some projects only sees the documents in those projects. Authenticate with `Authorization: Bearer scur_…` (create tokens in Settings → API tokens). Write documents as described in the authoring guide at /guide.md."},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/documents":{"get":{"operationId":"listDocuments","summary":"List documents (newest first, or ranked by relevance when q is given)","x-scope":"documents:read","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Full-text search (web search syntax)."},{"name":"tag","in":"query","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"description":"Repeat to require several tags."},{"name":"project","in":"query","schema":{"type":"string","description":"A project id, or \"none\" for documents without a project."},"description":"Only documents of this project (\"none\": without a project)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"nextCursor from the previous page."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"A page of documents.","content":{"application/json":{"schema":{"type":"object","required":["items","nextCursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummary"}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid query parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createDocument","summary":"Create a document from Markdown","x-scope":"documents:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"fileName":{"type":"string","maxLength":200,"description":"Defaults to a name made from the title."},"content":{"type":"string","description":"Markdown, at most 1 MB (UTF-8)."},"projectId":{"type":["string","null"],"format":"uuid","description":"Project to create the document in. Required for a token limited to several projects; defaults to the only one for a token limited to one."}}}}}},"responses":{"201":{"description":"Created. The Location header points to the document.","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["id","version","url"],"properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer"},"url":{"type":"string","format":"uri","description":"The document in the web app."}}}}}},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"The projectId is not one of your projects (or outside the token’s projects).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"The body or the content is larger than 1 MB.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Malformed JSON or invalid fields.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/documents/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Document id (UUID).","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getDocument","summary":"Get a document with its Markdown","x-scope":"documents:read","responses":{"200":{"description":"The document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such document for this user.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"updateDocument","summary":"Replace the content (and optionally the file name)","x-scope":"documents:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content","expectedVersion"],"properties":{"content":{"type":"string"},"fileName":{"type":"string","maxLength":200},"expectedVersion":{"type":"integer","minimum":1,"description":"The version you last read."}}}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object","required":["version"],"properties":{"version":{"type":"integer"}}}}}},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such document for this user.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The document changed since expectedVersion; the problem carries currentVersion.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"The body or the content is larger than 1 MB.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Malformed JSON or invalid fields.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"moveDocument","summary":"Move a document into a project, or out of its project","x-scope":"documents:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectId"],"properties":{"projectId":{"type":["string","null"],"format":"uuid","description":"null removes it from its project."}}}}}},"responses":{"200":{"description":"Moved. The version does not change (moving is not a content change).","content":{"application/json":{"schema":{"type":"object","required":["id","projectId"],"properties":{"id":{"type":"string","format":"uuid"},"projectId":{"type":["string","null"],"format":"uuid"}}}}}},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such document or project for this user.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"The body is larger than 1 MB.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Malformed JSON or invalid fields.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteDocument","summary":"Move a document to the trash","x-scope":"documents:write","responses":{"204":{"description":"Moved to the trash (restorable in the web app)."},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such document for this user.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/documents/{id}/raw":{"parameters":[{"name":"id","in":"path","required":true,"description":"Document id (UUID).","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getDocumentRaw","summary":"Get the stored Markdown byte for byte","x-scope":"documents:read","parameters":[{"name":"download","in":"query","schema":{"type":"string","enum":["1"]},"description":"Adds Content-Disposition: attachment."}],"responses":{"200":{"description":"The Markdown.","content":{"text/markdown":{"schema":{"type":"string"}}}},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such document for this user.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects":{"get":{"operationId":"listProjects","summary":"List projects by name","x-scope":"documents:read","responses":{"200":{"description":"The projects (a project-limited token sees only its projects).","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}}}}}},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createProject","summary":"Create a project","x-scope":"documents:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":2000}}}}}},"responses":{"201":{"description":"Created. The Location header points to the project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectWithDocuments"}}},"headers":{"Location":{"schema":{"type":"string"}}}},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"A project with this name exists already (names ignore case).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"The body is larger than 1 MB.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Malformed JSON or invalid fields.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Project id (UUID).","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getProject","summary":"Get a project with its documents in order","x-scope":"documents:read","responses":{"200":{"description":"The project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectWithDocuments"}}}},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project for this user.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updateProject","summary":"Rename, describe, set the home document or reorder","x-scope":"documents:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Needs a token not limited to projects."},"description":{"type":"string","maxLength":2000},"homeDocumentId":{"type":["string","null"],"format":"uuid","description":"A document of this project, or null."},"documentOrder":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Every document id of the project, each once, in the new order."}}}}}},"responses":{"200":{"description":"The updated project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectWithDocuments"}}}},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project for this user.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"A project with this name exists already.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"The body is larger than 1 MB.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Malformed JSON, invalid fields, a foreign home document or an incomplete order.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteProject","summary":"Delete a project","x-scope":"documents:write","parameters":[{"name":"documents","in":"query","schema":{"type":"string","enum":["keep","trash"],"default":"keep"},"description":"keep: the documents stay without a project; trash: they move to the trash."}],"responses":{"204":{"description":"Deleted, with its share links."},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project for this user.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid documents parameter.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{id}/export":{"parameters":[{"name":"id","in":"path","required":true,"description":"Project id (UUID).","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"exportProject","summary":"Download the project as a zip","x-scope":"documents:read","responses":{"200":{"description":"<project>/<file name> for each document in order, plus project.json.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing, invalid or revoked token (and no session).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the required scope, or is limited to projects and the action needs full access.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project for this user.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Too many documents for one export.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per token). See the Retry-After header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API token: scur_<prefix>_<secret>"}},"schemas":{"DocumentSummary":{"type":"object","required":["id","title","fileName","tags","projectId","version","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"fileName":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"projectId":{"type":["string","null"],"format":"uuid"},"version":{"type":"integer"},"updatedAt":{"type":"string","format":"date-time"}}},"Document":{"type":"object","required":["id","title","fileName","content","tags","projectId","version","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"fileName":{"type":"string"},"content":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"projectId":{"type":["string","null"],"format":"uuid"},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Project":{"type":"object","required":["id","name","description","documentCount","homeDocumentId","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"documentCount":{"type":"integer"},"homeDocumentId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time","description":"Includes changes to its documents."}}},"ProjectWithDocuments":{"allOf":[{"$ref":"#/components/schemas/Project"},{"type":"object","required":["documents"],"properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummary"}}}}]},"Problem":{"type":"object","description":"RFC 9457 problem details.","required":["type","title","status","detail"],"properties":{"type":{"type":"string","enum":["/problems/unauthorized","/problems/forbidden","/problems/not-found","/problems/version-conflict","/problems/conflict","/problems/too-large","/problems/invalid-input","/problems/rate-limited","/problems/internal"]},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"currentVersion":{"type":"integer","description":"On 409: the stored version."},"retryAfterSeconds":{"type":"integer","description":"On 429."},"errors":{"type":"array","description":"On 422: the invalid fields.","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}}}