{ "schemes": [ "http", "https" ], "swagger": "2.0", "info": { "description": "API for Acontext.", "title": "Acontext API", "contact": {}, "version": "1.0" }, "basePath": "/api/v1", "paths": { "/admin/v1/project": { "post": { "description": "Create a new project with a randomly generated secret key", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "admin" ], "summary": "Create a new project", "parameters": [ { "description": "Project configuration", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/handler.CreateProjectReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.CreateProjectOutput" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/serializer.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/admin/v1/project/{project_id}": { "delete": { "description": "Delete a project by ID", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "admin" ], "summary": "Delete a project", "parameters": [ { "type": "string", "format": "uuid", "description": "Project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/serializer.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/admin/v1/project/{project_id}/metrics": { "get": { "description": "Get metrics for a project by querying Jaeger API with project_id filter", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "admin" ], "summary": "Analyze project metrics", "parameters": [ { "type": "string", "format": "uuid", "description": "Project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/admin/v1/project/{project_id}/secret_key": { "put": { "description": "Generate a new secret key for a non-encrypted project. Blocked for encrypted projects.", "produces": [ "application/json" ], "tags": [ "admin" ], "summary": "Rotate project secret key (admin)", "parameters": [ { "type": "string", "format": "uuid", "description": "Project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.UpdateSecretKeyOutput" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/serializer.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/admin/v1/project/{project_id}/statistics": { "get": { "description": "Get statistics for a project", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "admin" ], "summary": "Analyze project statistics", "parameters": [ { "type": "string", "format": "uuid", "description": "Project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/admin/v1/project/{project_id}/usages": { "get": { "description": "Get usage analytics for a project", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "admin" ], "summary": "Analyze project usages", "parameters": [ { "type": "string", "format": "uuid", "description": "Project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "default": 30, "description": "Number of days to analyze (default: 30)", "name": "interval_days", "in": "query" }, { "type": "string", "description": "Comma-separated list of fields to fetch (empty = all)", "name": "fields", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/agent_skills": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all agent skills under a project", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "agent_skills" ], "summary": "List agent skills", "parameters": [ { "type": "string", "example": "alice@acontext.io", "description": "User identifier to filter skills", "name": "user", "in": "query" }, { "type": "integer", "description": "Limit of agent skills to return, default 20. Max 200.", "name": "limit", "in": "query" }, { "type": "string", "description": "Cursor for pagination", "name": "cursor", "in": "query" }, { "type": "boolean", "description": "Order by created_at descending if true", "name": "time_desc", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.ListAgentSkillsOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# List all skills with pagination\nresult = client.skills.list_catalog(limit=50)\nfor skill in result.items:\n print(f\"{skill.name}: {skill.description}\")\n\n# Paginate through all skills\nif result.has_more:\n next_page = client.skills.list_catalog(cursor=result.next_cursor)\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// List all skills with pagination\nconst result = await client.skills.list_catalog({ limit: 50 });\nresult.items.forEach(skill =\u003e {\n console.log(`${skill.name}: ${skill.description}`);\n});\n\n// Paginate through all skills\nif (result.has_more) {\n const nextPage = await client.skills.list_catalog({ cursor: result.next_cursor });\n}\n" } ] }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Upload a zip file containing agent skill. The zip file must contain a SKILL.md file (case-insensitive) with YAML format containing 'name' and 'description' fields. The name and description will be extracted from SKILL.md. Files are stored as Disk Artifacts. Optionally associate with a user identifier.", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "agent_skills" ], "summary": "Create agent skill", "parameters": [ { "type": "file", "description": "ZIP file containing agent skill. Must contain SKILL.md (case-insensitive) with YAML format: name and description fields.", "name": "file", "in": "formData", "required": true }, { "type": "string", "example": "alice@acontext.io", "description": "User identifier to associate with the skill", "name": "user", "in": "formData" }, { "type": "string", "description": "Additional metadata (JSON string)", "name": "meta", "in": "formData" } ], "responses": { "201": { "description": "Returns agent skill with name and description extracted from SKILL.md", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.AgentSkills" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\nfrom acontext.uploads import FileUpload\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Upload a skill from a zip file\nwith open('my_skill.zip', 'rb') as f:\n skill = client.skills.create(\n file=FileUpload(filename='my_skill.zip', content=f.read(), content_type='application/zip'),\n user='alice@example.com',\n meta={'version': '1.0'}\n )\nprint(f\"Created skill: {skill.name} (ID: {skill.id})\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\nimport fs from 'fs';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Upload a skill from a zip file\nconst fileBuffer = fs.readFileSync('my_skill.zip');\nconst skill = await client.skills.create({\n file: ['my_skill.zip', fileBuffer, 'application/zip'],\n user: 'alice@example.com',\n meta: { version: '1.0' }\n});\nconsole.log(`Created skill: ${skill.name} (ID: ${skill.id})`);\n" } ] } }, "/agent_skills/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get agent skill by its UUID", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "agent_skills" ], "summary": "Get agent skill by ID", "parameters": [ { "type": "string", "description": "Agent skill UUID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.AgentSkills" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get a skill by ID\nskill = client.skills.get('skill-uuid-here')\nprint(f\"Skill: {skill.name}\")\nprint(f\"Description: {skill.description}\")\nprint(f\"Files: {len(skill.file_index)} file(s)\")\nfor f in skill.file_index:\n print(f\" - {f.path} ({f.mime})\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get a skill by ID\nconst skill = await client.skills.get('skill-uuid-here');\nconsole.log(`Skill: ${skill.name}`);\nconsole.log(`Description: ${skill.description}`);\nconsole.log(`Files: ${skill.file_index.length} file(s)`);\nskill.file_index.forEach(f =\u003e console.log(` - ${f.path} (${f.mime})`));\n" } ] }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete agent skill and all associated files", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "agent_skills" ], "summary": "Delete agent skill", "parameters": [ { "type": "string", "description": "Agent skill UUID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Delete a skill by ID\nclient.skills.delete('skill-uuid-here')\nprint('Skill deleted successfully')\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Delete a skill by ID\nawait client.skills.delete('skill-uuid-here');\nconsole.log('Skill deleted successfully');\n" } ] } }, "/agent_skills/{id}/download_to_sandbox": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Download all files from an agent skill to a sandbox environment. Files are placed at /skills/{skill_name}/.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "agent_skills" ], "summary": "Download skill to sandbox", "parameters": [ { "type": "string", "description": "Agent skill UUID", "name": "id", "in": "path", "required": true }, { "description": "Download to sandbox request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.DownloadSkillToSandboxReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.DownloadSkillToSandboxResp" } } } ] } }, "409": { "description": "Skill directory already exists in sandbox", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Download skill to sandbox\nresult = client.skills.download_to_sandbox(\n skill_id='skill-uuid',\n sandbox_id='sandbox-uuid'\n)\nprint(f\"Success: {result.success}\")\nprint(f\"Skill installed at: {result.dir_path}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Download skill to sandbox\nconst result = await client.skills.downloadToSandbox('skill-uuid', {\n sandboxId: 'sandbox-uuid'\n});\nconsole.log(`Success: ${result.success}`);\nconsole.log(`Skill installed at: ${result.dir_path}`);\n" } ] } }, "/agent_skills/{id}/download_zip": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Download all files from an agent skill as a ZIP archive. Files are streamed directly with their relative paths preserved.", "consumes": [ "application/json" ], "produces": [ "application/zip" ], "tags": [ "agent_skills" ], "summary": "Download skill as ZIP file", "parameters": [ { "type": "string", "description": "Agent skill UUID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "ZIP file containing all skill files", "schema": { "type": "file" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Download skill as ZIP file\nwith open('my_skill.zip', 'wb') as f:\n content = client.skills.download_zip('skill-uuid')\n f.write(content)\nprint('Skill downloaded as ZIP')\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\nimport fs from 'fs';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Download skill as ZIP file\nconst zipContent = await client.skills.downloadZip('skill-uuid');\nfs.writeFileSync('my_skill.zip', zipContent);\nconsole.log('Skill downloaded as ZIP');\n" } ] } }, "/agent_skills/{id}/file": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get file content or download URL from agent skill. If the file is text-based (parseable), returns parsed content. Otherwise, returns a presigned download URL.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "agent_skills" ], "summary": "Get file from agent skill", "parameters": [ { "type": "string", "description": "Agent skill UUID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "File path within the skill (e.g., 'scripts/extract_text.json')", "name": "file_path", "in": "query", "required": true }, { "type": "integer", "description": "URL expiration in seconds for presigned URL (default 900)", "name": "expire", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.GetFileOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get a file from a skill (text files return content, binary files return URL)\nfile_resp = client.skills.get_file(\n skill_id='skill-uuid-here',\n file_path='scripts/main.py',\n expire=1800 # URL expires in 30 minutes\n)\n\nprint(f\"File: {file_resp.path} ({file_resp.mime})\")\nif file_resp.content:\n print(f\"Content: {file_resp.content.raw}\")\nif file_resp.url:\n print(f\"Download URL: {file_resp.url}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get a file from a skill (text files return content, binary files return URL)\nconst fileResp = await client.skills.getFile({\n skillId: 'skill-uuid-here',\n filePath: 'scripts/main.py',\n expire: 1800 // URL expires in 30 minutes\n});\n\nconsole.log(`File: ${fileResp.path} (${fileResp.mime})`);\nif (fileResp.content) {\n console.log(`Content: ${fileResp.content.raw}`);\n}\nif (fileResp.url) {\n console.log(`Download URL: ${fileResp.url}`);\n}\n" } ] } }, "/disk": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all disks under a project", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "disk" ], "summary": "List disks", "parameters": [ { "type": "string", "example": "alice@acontext.io", "description": "User identifier to filter disks", "name": "user", "in": "query" }, { "type": "integer", "description": "Limit of disks to return, default 20. Max 200.", "name": "limit", "in": "query" }, { "type": "string", "description": "Cursor for pagination. Use the cursor from the previous response to get the next page.", "name": "cursor", "in": "query" }, { "type": "boolean", "example": false, "description": "Order by created_at descending if true, ascending if false (default false)", "name": "time_desc", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.ListDisksOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# List disks\ndisks = client.disks.list(limit=10, time_desc=True)\nfor disk in disks.items:\n print(f\"Disk: {disk.id}\")\n\n# List disks for a specific user\ndisks = client.disks.list(user='alice@acontext.io', limit=10)\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// List disks\nconst disks = await client.disks.list({ limit: 10, timeDesc: true });\nfor (const disk of disks.items) {\n console.log(`Disk: ${disk.id}`);\n}\n\n// List disks for a specific user\nconst userDisks = await client.disks.list({ user: 'alice@acontext.io', limit: 10 });\n" } ] }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a disk group under a project. Optionally associate with a user identifier.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "disk" ], "summary": "Create disk", "parameters": [ { "description": "CreateDisk payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.CreateDiskReq" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.Disk" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Create a disk\ndisk = client.disks.create()\nprint(f\"Created disk: {disk.id}\")\n\n# Create a disk for a specific user\ndisk = client.disks.create(user='alice@acontext.io')\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Create a disk\nconst disk = await client.disks.create();\nconsole.log(`Created disk: ${disk.id}`);\n\n// Create a disk for a specific user\nconst userDisk = await client.disks.create({ user: 'alice@acontext.io' });\n" } ] } }, "/disk/{disk_id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete a disk by its UUID", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "disk" ], "summary": "Delete disk", "parameters": [ { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "description": "Disk ID", "name": "disk_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Delete a disk\nclient.disks.delete(disk_id='disk-uuid')\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Delete a disk\nawait client.disks.delete('disk-uuid');\n" } ] } }, "/disk/{disk_id}/artifact": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get artifact information by path and filename. Optionally include a presigned URL for downloading and parsed file content.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "artifact" ], "summary": "Get artifact", "parameters": [ { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "description": "Disk ID", "name": "disk_id", "in": "path", "required": true }, { "type": "string", "example": "/documents/report.pdf", "description": "File path including filename", "name": "file_path", "in": "query", "required": true }, { "type": "boolean", "example": true, "description": "Whether to return public URL, default is true", "name": "with_public_url", "in": "query" }, { "type": "boolean", "example": true, "description": "Whether to return parsed file content, default is true", "name": "with_content", "in": "query" }, { "type": "integer", "example": 3600, "description": "Expire time in seconds for presigned URL (default: 3600)", "name": "expire", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.GetArtifactResp" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get artifact information\nartifact_info = client.disks.get_artifact(\n disk_id='disk-uuid',\n file_path='/documents/report.pdf',\n with_public_url=True,\n with_content=True,\n expire=3600\n)\nprint(f\"Artifact: {artifact_info.artifact.filename}\")\nif artifact_info.public_url:\n print(f\"Download URL: {artifact_info.public_url}\")\nif artifact_info.content:\n print(f\"Content: {artifact_info.content.text[:100]}...\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get artifact information\nconst artifactInfo = await client.disks.getArtifact('disk-uuid', {\n filePath: '/documents/report.pdf',\n withPublicUrl: true,\n withContent: true,\n expire: 3600\n});\nconsole.log(`Artifact: ${artifactInfo.artifact.filename}`);\nif (artifactInfo.publicUrl) {\n console.log(`Download URL: ${artifactInfo.publicUrl}`);\n}\nif (artifactInfo.content) {\n console.log(`Content: ${artifactInfo.content.text.substring(0, 100)}...`);\n}\n" } ] }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update an artifact's metadata (user-defined metadata only)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "artifact" ], "summary": "Update artifact meta", "parameters": [ { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "description": "Disk ID", "name": "disk_id", "in": "path", "required": true }, { "description": "Update artifact request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.UpdateArtifactReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.UpdateArtifactResp" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Update artifact metadata\nartifact = client.disks.update_artifact(\n disk_id='disk-uuid',\n file_path='/documents/report.pdf',\n meta={'category': 'updated', 'reviewed': True, 'version': 2}\n)\nprint(f\"Updated artifact: {artifact.artifact.id}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Update artifact metadata\nconst artifact = await client.disks.updateArtifact('disk-uuid', {\n filePath: '/documents/report.pdf',\n meta: { category: 'updated', reviewed: true, version: 2 }\n});\nconsole.log(`Updated artifact: ${artifact.artifact.id}`);\n" } ] }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Upload a file and create or update an artifact record under a disk. File size must not exceed the configured maximum upload size limit (default: 16MB).", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "artifact" ], "summary": "Upsert artifact", "parameters": [ { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "description": "Disk ID", "name": "disk_id", "in": "path", "required": true }, { "type": "string", "description": "File path in the disk storage (optional, defaults to '/')", "name": "file_path", "in": "formData" }, { "type": "file", "description": "File to upload (size must not exceed configured limit)", "name": "file", "in": "formData", "required": true }, { "type": "string", "description": "Custom metadata as JSON string (optional, system metadata will be stored under '__artifact_info__' key)", "name": "meta", "in": "formData" } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.Artifact" } } } ] } }, "413": { "description": "File size exceeds maximum allowed size", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Upload a file to disk\nwith open('report.pdf', 'rb') as f:\n artifact = client.disks.upload_artifact(\n disk_id='disk-uuid',\n file=f,\n file_path='/documents/',\n meta={'category': 'reports', 'year': 2024}\n )\nprint(f\"Uploaded artifact: {artifact.id}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\nimport fs from 'fs';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Upload a file to disk\nconst fileBuffer = fs.readFileSync('report.pdf');\nconst artifact = await client.disks.uploadArtifact('disk-uuid', {\n file: fileBuffer,\n filePath: '/documents/',\n meta: { category: 'reports', year: 2024 }\n});\nconsole.log(`Uploaded artifact: ${artifact.id}`);\n" } ] }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete an artifact by path and filename", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "artifact" ], "summary": "Delete artifact", "parameters": [ { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "description": "Disk ID", "name": "disk_id", "in": "path", "required": true }, { "type": "string", "example": "/documents/report.pdf", "description": "File path including filename", "name": "file_path", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Delete an artifact\nclient.disks.delete_artifact(\n disk_id='disk-uuid',\n file_path='/documents/report.pdf'\n)\nprint('Artifact deleted successfully')\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Delete an artifact\nawait client.disks.deleteArtifact('disk-uuid', {\n filePath: '/documents/report.pdf'\n});\nconsole.log('Artifact deleted successfully');\n" } ] } }, "/disk/{disk_id}/artifact/download": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Download raw artifact file content. Decrypts content if encryption is enabled.", "produces": [ "application/octet-stream" ], "tags": [ "artifact" ], "summary": "Download artifact content", "parameters": [ { "type": "string", "format": "uuid", "description": "Disk ID", "name": "disk_id", "in": "path", "required": true }, { "type": "string", "description": "File path including filename", "name": "file_path", "in": "query", "required": true } ], "responses": { "200": { "description": "File content" } } } }, "/disk/{disk_id}/artifact/download_to_sandbox": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Download an artifact from disk storage to a sandbox environment", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "artifact" ], "summary": "Download artifact to sandbox", "parameters": [ { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "description": "Disk ID", "name": "disk_id", "in": "path", "required": true }, { "description": "Download to sandbox request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.DownloadToSandboxReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.DownloadToSandboxResp" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Download artifact to sandbox\nresult = client.disks.artifacts.download_to_sandbox(\n disk_id='disk-uuid',\n file_path='/documents/',\n filename='report.pdf',\n sandbox_id='sandbox-uuid',\n sandbox_path='/home/user/'\n)\nprint(f\"Success: {result.success}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Download artifact to sandbox\nconst result = await client.disks.artifacts.downloadToSandbox('disk-uuid', {\n filePath: '/documents/',\n filename: 'report.pdf',\n sandboxId: 'sandbox-uuid',\n sandboxPath: '/home/user/'\n});\nconsole.log(`Success: ${result.success}`);\n" } ] } }, "/disk/{disk_id}/artifact/glob": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Search through artifact file paths using glob patterns (*, ?, etc.)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "artifact" ], "summary": "Search artifact paths with glob patterns", "parameters": [ { "type": "string", "format": "uuid", "description": "Disk ID", "name": "disk_id", "in": "path", "required": true }, { "type": "string", "description": "Glob pattern (e.g., '**/*.py', '*.txt')", "name": "query", "in": "query", "required": true }, { "type": "integer", "description": "Maximum number of results (default 100, max 1000)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/model.Artifact" } } } } ] } } } } }, "/disk/{disk_id}/artifact/grep": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Search through text-based artifact content using regex patterns", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "artifact" ], "summary": "Search artifact content with regex", "parameters": [ { "type": "string", "format": "uuid", "description": "Disk ID", "name": "disk_id", "in": "path", "required": true }, { "type": "string", "description": "Regex pattern to search for", "name": "query", "in": "query", "required": true }, { "type": "integer", "description": "Maximum number of results (default 100, max 1000)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/model.Artifact" } } } } ] } } } } }, "/disk/{disk_id}/artifact/ls": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List artifacts in a specific path or all artifacts in a disk", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "artifact" ], "summary": "List artifacts", "parameters": [ { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "description": "Disk ID", "name": "disk_id", "in": "path", "required": true }, { "type": "string", "description": "Path filter (optional, defaults to root '/')", "name": "path", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.ListArtifactsResp" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# List artifacts in a path\nresult = client.disks.list_artifacts(\n disk_id='disk-uuid',\n path='/documents/'\n)\nprint(f\"Found {len(result.artifacts)} artifacts\")\nfor artifact in result.artifacts:\n print(f\" - {artifact.path}{artifact.filename}\")\nprint(f\"Subdirectories: {', '.join(result.directories)}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// List artifacts in a path\nconst result = await client.disks.listArtifacts('disk-uuid', {\n path: '/documents/'\n});\nconsole.log(`Found ${result.artifacts.length} artifacts`);\nfor (const artifact of result.artifacts) {\n console.log(` - ${artifact.path}${artifact.filename}`);\n}\nconsole.log(`Subdirectories: ${result.directories.join(', ')}`);\n" } ] } }, "/disk/{disk_id}/artifact/upload_from_sandbox": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Upload a file from a sandbox environment to disk storage as an artifact", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "artifact" ], "summary": "Upload file from sandbox to disk", "parameters": [ { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "description": "Disk ID", "name": "disk_id", "in": "path", "required": true }, { "description": "Upload from sandbox request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.UploadFromSandboxReq" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.Artifact" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Upload file from sandbox to disk\nartifact = client.disks.artifacts.upload_from_sandbox(\n disk_id='disk-uuid',\n sandbox_id='sandbox-uuid',\n sandbox_path='/home/user/',\n sandbox_filename='output.txt',\n file_path='/results/'\n)\nprint(f\"Created: {artifact.path}{artifact.filename}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Upload file from sandbox to disk\nconst artifact = await client.disks.artifacts.uploadFromSandbox('disk-uuid', {\n sandboxId: 'sandbox-uuid',\n sandboxPath: '/home/user/',\n sandboxFilename: 'output.txt',\n filePath: '/results/'\n});\nconsole.log(`Created: ${artifact.path}${artifact.filename}`);\n" } ] } }, "/learning_spaces": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List learning spaces with optional user, meta filter, and cursor pagination.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "learning_spaces" ], "summary": "List learning spaces", "parameters": [ { "type": "string", "description": "Filter by user identifier", "name": "user", "in": "query" }, { "type": "integer", "description": "Limit per page, default 20, max 200", "name": "limit", "in": "query" }, { "type": "string", "description": "Cursor for pagination", "name": "cursor", "in": "query" }, { "type": "boolean", "description": "Order by created_at descending", "name": "time_desc", "in": "query" }, { "type": "string", "description": "URL-encoded JSON for JSONB containment filter", "name": "filter_by_meta", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.ListLearningSpacesOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# List learning spaces\nresult = client.learning_spaces.list(limit=20, time_desc=True)\nfor space in result.items:\n print(f\"{space.id}: {space.meta}\")\n\n# List with user filter\nresult = client.learning_spaces.list(user='alice@acontext.io')\n\n# List with meta filter\nresult = client.learning_spaces.list(\n filter_by_meta={'version': '1.0'}\n)\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// List learning spaces\nconst result = await client.learningSpaces.list({ limit: 20, timeDesc: true });\nfor (const space of result.items) {\n console.log(`${space.id}: ${JSON.stringify(space.meta)}`);\n}\n\n// List with user filter\nconst userSpaces = await client.learningSpaces.list({ user: 'alice@acontext.io' });\n\n// List with meta filter\nconst filtered = await client.learningSpaces.list({\n filterByMeta: { version: '1.0' }\n});\n" } ] }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new learning space. Optionally associate with a user.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "learning_spaces" ], "summary": "Create learning space", "parameters": [ { "description": "Create learning space request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.CreateLearningSpaceReq" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.LearningSpace" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Create a learning space\nspace = client.learning_spaces.create(\n user='alice@acontext.io',\n meta={'version': '1.0'}\n)\nprint(f\"Created space: {space.id}\")\n\n# Create a learning space without a user\nspace = client.learning_spaces.create()\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Create a learning space\nconst space = await client.learningSpaces.create({\n user: 'alice@acontext.io',\n meta: { version: '1.0' }\n});\nconsole.log(`Created space: ${space.id}`);\n\n// Create a learning space without a user\nconst space2 = await client.learningSpaces.create();\n" } ] } }, "/learning_spaces/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get a learning space by ID.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "learning_spaces" ], "summary": "Get learning space", "parameters": [ { "type": "string", "description": "Learning space UUID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.LearningSpace" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get a learning space by ID\nspace = client.learning_spaces.get('space-uuid')\nprint(f\"Space: {space.id}\")\nprint(f\"Meta: {space.meta}\")\nprint(f\"Created at: {space.created_at}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get a learning space by ID\nconst space = await client.learningSpaces.get('space-uuid');\nconsole.log(`Space: ${space.id}`);\nconsole.log(`Meta: ${JSON.stringify(space.meta)}`);\nconsole.log(`Created at: ${space.created_at}`);\n" } ] }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete a learning space. Junction records are cascade-deleted by the DB.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "learning_spaces" ], "summary": "Delete learning space", "parameters": [ { "type": "string", "description": "Learning space UUID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Delete a learning space\nclient.learning_spaces.delete('space-uuid')\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Delete a learning space\nawait client.learningSpaces.delete('space-uuid');\n" } ] }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Merge provided meta into existing meta. Existing keys not in the request are preserved.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "learning_spaces" ], "summary": "Update learning space (patch meta)", "parameters": [ { "type": "string", "description": "Learning space UUID", "name": "id", "in": "path", "required": true }, { "description": "Patch meta request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.UpdateLearningSpaceReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.LearningSpace" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Update a learning space's meta (patch semantics)\nspace = client.learning_spaces.update(\n 'space-uuid',\n meta={'version': '2.0', 'environment': 'production'}\n)\nprint(f\"Updated meta: {space.meta}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Update a learning space's meta (patch semantics)\nconst space = await client.learningSpaces.update('space-uuid', {\n meta: { version: '2.0', environment: 'production' }\n});\nconsole.log(`Updated meta: ${JSON.stringify(space.meta)}`);\n" } ] } }, "/learning_spaces/{id}/learn": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Create an async learning record from a session. Initially stays in pending status.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "learning_spaces" ], "summary": "Learn from session", "parameters": [ { "type": "string", "description": "Learning space UUID", "name": "id", "in": "path", "required": true }, { "description": "Learn request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.LearnReq" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.LearningSpaceSession" } } } ] } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/serializer.Response" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Learn from a session\nrecord = client.learning_spaces.learn(\n 'space-uuid',\n session_id='session-uuid'\n)\nprint(f\"Learning record: {record.id}, status: {record.status}\")\n\n# Wait for learning to complete\nresult = client.learning_spaces.wait_for_learning(\n 'space-uuid',\n session_id='session-uuid',\n timeout=120.0\n)\nprint(f\"Final status: {result.status}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Learn from a session\nconst record = await client.learningSpaces.learn({\n spaceId: 'space-uuid',\n sessionId: 'session-uuid'\n});\nconsole.log(`Learning record: ${record.id}, status: ${record.status}`);\n\n// Wait for learning to complete\nconst result = await client.learningSpaces.waitForLearning({\n spaceId: 'space-uuid',\n sessionId: 'session-uuid',\n timeout: 120\n});\nconsole.log(`Final status: ${result.status}`);\n" } ] } }, "/learning_spaces/{id}/sessions": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all learning session records for a space, including their processing status.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "learning_spaces" ], "summary": "List sessions in space", "parameters": [ { "type": "string", "description": "Learning space UUID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/model.LearningSpaceSession" } } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# List all learning sessions in a space\nsessions = client.learning_spaces.list_sessions('space-uuid')\nfor s in sessions:\n print(f\"Session {s.session_id}: {s.status}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// List all learning sessions in a space\nconst sessions = await client.learningSpaces.listSessions('space-uuid');\nfor (const s of sessions) {\n console.log(`Session ${s.session_id}: ${s.status}`);\n}\n" } ] } }, "/learning_spaces/{id}/sessions/{session_id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get a single learning session record by session ID within a learning space.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "learning_spaces" ], "summary": "Get session in space", "parameters": [ { "type": "string", "description": "Learning space UUID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Session UUID", "name": "session_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.LearningSpaceSession" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/serializer.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get a learning session record\nsession = client.learning_spaces.get_session(\n 'space-uuid',\n session_id='session-uuid'\n)\nprint(f\"Session {session.session_id}: {session.status}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get a learning session record\nconst session = await client.learningSpaces.getSession({\n spaceId: 'space-uuid',\n sessionId: 'session-uuid'\n});\nconsole.log(`Session ${session.session_id}: ${session.status}`);\n" } ] } }, "/learning_spaces/{id}/skills": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List all skills associated with a learning space. Returns full skill data.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "learning_spaces" ], "summary": "List skills in space", "parameters": [ { "type": "string", "description": "Learning space UUID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/model.AgentSkills" } } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# List all skills in a learning space\nskills = client.learning_spaces.list_skills('space-uuid')\nfor skill in skills:\n print(f\"{skill.name}: {skill.description}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// List all skills in a learning space\nconst skills = await client.learningSpaces.listSkills('space-uuid');\nfor (const skill of skills) {\n console.log(`${skill.name}: ${skill.description}`);\n}\n" } ] }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Add a skill to a learning space.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "learning_spaces" ], "summary": "Include skill in space", "parameters": [ { "type": "string", "description": "Learning space UUID", "name": "id", "in": "path", "required": true }, { "description": "Include skill request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.IncludeSkillReq" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.LearningSpaceSkill" } } } ] } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/serializer.Response" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Include a skill in a learning space\nrecord = client.learning_spaces.include_skill(\n 'space-uuid',\n skill_id='skill-uuid'\n)\nprint(f\"Linked skill {record.skill_id} to space {record.learning_space_id}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Include a skill in a learning space\nconst record = await client.learningSpaces.includeSkill({\n spaceId: 'space-uuid',\n skillId: 'skill-uuid'\n});\nconsole.log(`Linked skill ${record.skill_id} to space ${record.learning_space_id}`);\n" } ] } }, "/learning_spaces/{id}/skills/{skill_id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Remove a skill from a learning space. Idempotent — silently succeeds if not associated.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "learning_spaces" ], "summary": "Exclude skill from space", "parameters": [ { "type": "string", "description": "Learning space UUID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Skill UUID", "name": "skill_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Exclude a skill from a learning space (idempotent)\nclient.learning_spaces.exclude_skill(\n 'space-uuid',\n skill_id='skill-uuid'\n)\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Exclude a skill from a learning space (idempotent)\nawait client.learningSpaces.excludeSkill({\n spaceId: 'space-uuid',\n skillId: 'skill-uuid'\n});\n" } ] } }, "/material/{token}": { "get": { "description": "Download file content via a material token. No authentication required. Returns the file content with appropriate Content-Type header.", "produces": [ "application/octet-stream" ], "tags": [ "material" ], "summary": "Serve material content", "parameters": [ { "type": "string", "description": "Material token (64-char hex)", "name": "token", "in": "path", "required": true } ], "responses": { "200": { "description": "File content" }, "404": { "description": "Token not found or expired", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/metrics/v1": { "post": { "description": "Create storage metrics, fetch metrics, push to external API, and store quota status in Redis", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "metrics" ], "summary": "Push metrics to external API", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/serializer.Response" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/serializer.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/metrics/v1/:project_id/quota": { "get": { "description": "Get quota information for a project based on path and method", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "metrics" ], "summary": "Get project quota", "parameters": [ { "type": "string", "description": "Project ID", "name": "project_id", "in": "path", "required": true }, { "type": "string", "description": "Path", "name": "path", "in": "query", "required": true }, { "type": "string", "description": "Method", "name": "method", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/project/configs": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the project-level configuration (stored under the \"project_config\" key).", "produces": [ "application/json" ], "tags": [ "Project" ], "summary": "Get project configs", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Merges the provided keys into the project-level configuration. Keys with null values are deleted (reset to default).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Project" ], "summary": "Patch project configs", "parameters": [ { "description": "Config keys to merge", "name": "body", "in": "body", "required": true, "schema": { "type": "object", "additionalProperties": true } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/project/decrypt": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Decrypts all existing S3 data for the project and disables encryption for future writes.", "produces": [ "application/json" ], "tags": [ "Project" ], "summary": "Disable project encryption", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/serializer.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/project/encrypt": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Encrypts all existing S3 data for the project and enables encryption for future writes.", "produces": [ "application/json" ], "tags": [ "Project" ], "summary": "Enable project encryption", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/serializer.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/serializer.Response" } } } } }, "/sandbox": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Create and start a new sandbox for the project", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "sandbox" ], "summary": "Create a new sandbox", "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/httpclient.SandboxRuntimeInfo" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Create a new sandbox\nsandbox = client.sandboxes.create()\nprint(f\"Sandbox ID: {sandbox.sandbox_id}\")\nprint(f\"Status: {sandbox.sandbox_status}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Create a new sandbox\nconst sandbox = await client.sandboxes.create();\nconsole.log(`Sandbox ID: ${sandbox.sandbox_id}`);\nconsole.log(`Status: ${sandbox.sandbox_status}`);\n" } ] } }, "/sandbox/logs": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get sandbox logs for the project with cursor-based pagination", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "sandbox" ], "summary": "Get sandbox logs", "parameters": [ { "type": "integer", "description": "Limit of sandbox logs to return, default 20. Max 200.", "name": "limit", "in": "query" }, { "type": "string", "description": "Cursor for pagination. Use the cursor from the previous response to get the next page.", "name": "cursor", "in": "query" }, { "type": "boolean", "example": false, "description": "Order by created_at descending if true, ascending if false (default false)", "name": "time_desc", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.GetSandboxLogsOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get sandbox logs\nlogs = client.sandboxes.get_logs(limit=20, time_desc=True)\nfor log in logs.items:\n print(f\"Log {log.id}: {log.backend_type}\")\n\n# If there are more logs, use the cursor for pagination\nif logs.has_more:\n next_logs = client.sandboxes.get_logs(\n limit=20,\n cursor=logs.next_cursor\n )\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get sandbox logs\nconst logs = await client.sandboxes.getLogs({ limit: 20, timeDesc: true });\nfor (const log of logs.items) {\n console.log(`Log ${log.id}: ${log.backend_type}`);\n}\n\n// If there are more logs, use the cursor for pagination\nif (logs.hasMore) {\n const nextLogs = await client.sandboxes.getLogs({\n limit: 20,\n cursor: logs.nextCursor\n });\n}\n" } ] } }, "/sandbox/{sandbox_id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Kill a running sandbox", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "sandbox" ], "summary": "Kill a sandbox", "parameters": [ { "type": "string", "description": "Sandbox ID", "name": "sandbox_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/httpclient.FlagResponse" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Kill a sandbox\nresult = client.sandboxes.kill(sandbox_id='sandbox-uuid')\nprint(f\"Status: {result.status}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Kill a sandbox\nconst result = await client.sandboxes.kill('sandbox-uuid');\nconsole.log(`Status: ${result.status}`);\n" } ] } }, "/sandbox/{sandbox_id}/exec": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Execute a shell command in the specified sandbox", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "sandbox" ], "summary": "Execute command in sandbox", "parameters": [ { "type": "string", "description": "Sandbox ID", "name": "sandbox_id", "in": "path", "required": true }, { "description": "Command to execute", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.ExecCommandReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/httpclient.SandboxCommandOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Execute a command in the sandbox\nresult = client.sandboxes.exec_command(\n sandbox_id='sandbox-uuid',\n command='ls -la'\n)\nprint(f\"stdout: {result.stdout}\")\nprint(f\"stderr: {result.stderr}\")\nprint(f\"exit_code: {result.exit_code}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Execute a command in the sandbox\nconst result = await client.sandboxes.execCommand({\n sandboxId: 'sandbox-uuid',\n command: 'ls -la'\n});\nconsole.log(`stdout: ${result.stdout}`);\nconsole.log(`stderr: ${result.stderr}`);\nconsole.log(`exit_code: ${result.exit_code}`);\n" } ] } }, "/session": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get all sessions under a project, optionally filtered by user or configs", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Get sessions", "parameters": [ { "type": "string", "example": "alice@acontext.io", "description": "User identifier to filter sessions", "name": "user", "in": "query" }, { "type": "string", "description": "JSON-encoded object for JSONB containment filter. Example: {\\", "name": "filter_by_configs", "in": "query" }, { "type": "integer", "description": "Limit of sessions to return, default 20. Max 200.", "name": "limit", "in": "query" }, { "type": "string", "description": "Cursor for pagination. Use the cursor from the previous response to get the next page.", "name": "cursor", "in": "query" }, { "type": "boolean", "example": false, "description": "Order by created_at descending if true, ascending if false (default false)", "name": "time_desc", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.ListSessionsOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# List sessions\nsessions = client.sessions.list(\n limit=20,\n time_desc=True\n)\nfor session in sessions.items:\n print(f\"{session.id}\")\n\n# List sessions for a specific user\nsessions = client.sessions.list(user='alice@acontext.io', limit=20)\n\n# List sessions filtered by configs\nsessions = client.sessions.list(\n limit=20,\n filter_by_configs={\"agent\": \"bot1\"}\n)\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// List sessions\nconst sessions = await client.sessions.list({\n limit: 20,\n timeDesc: true\n});\nfor (const session of sessions.items) {\n console.log(`${session.id}`);\n}\n\n// List sessions for a specific user\nconst userSessions = await client.sessions.list({ user: 'alice@acontext.io', limit: 20 });\n\n// List sessions filtered by configs\nconst filteredSessions = await client.sessions.list({\n limit: 20,\n filterByConfigs: { agent: 'bot1' }\n});\n" } ] }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new session. Optionally associate with a user identifier. You can also specify a custom UUID using use_uuid.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Create session", "parameters": [ { "description": "CreateSession payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.CreateSessionReq" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.Session" } } } ] } }, "400": { "description": "Invalid UUID format", "schema": { "$ref": "#/definitions/serializer.Response" } }, "409": { "description": "Session with this UUID already exists", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Create a session\nsession = client.sessions.create()\nprint(f\"Created session: {session.id}\")\n\n# Create a session for a specific user\nsession = client.sessions.create(user='alice@acontext.io')\n\n# Create a session with a specific UUID\nsession = client.sessions.create(use_uuid='123e4567-e89b-12d3-a456-426614174000')\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Create a session\nconst session = await client.sessions.create();\nconsole.log(`Created session: ${session.id}`);\n\n// Create a session for a specific user\nconst userSession = await client.sessions.create({ user: 'alice@acontext.io' });\n\n// Create a session with a specific UUID\nconst customSession = await client.sessions.create({ useUuid: '123e4567-e89b-12d3-a456-426614174000' });\n" } ] } }, "/session/{session_id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete a session by id", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Delete session", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Delete a session\nclient.sessions.delete(session_id='session-uuid')\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Delete a session\nawait client.sessions.delete('session-uuid');\n" } ] } }, "/session/{session_id}/asset/download": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Download a session asset (file attachment) by its S3 key. Decrypts if encryption is enabled.", "produces": [ "application/octet-stream" ], "tags": [ "session" ], "summary": "Download session asset", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true }, { "type": "string", "description": "S3 key of the asset", "name": "s3_key", "in": "query", "required": true } ], "responses": { "200": { "description": "Asset content" } } } }, "/session/{session_id}/configs": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get session configs by id", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Get session configs", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.Session" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get session configs\nsession = client.sessions.get_configs(session_id='session-uuid')\nprint(session.configs)\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get session configs\nconst session = await client.sessions.getConfigs('session-uuid');\nconsole.log(session.configs);\n" } ] }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update session configs by id", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Update session configs", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true }, { "description": "UpdateSessionConfigs payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.UpdateSessionConfigsReq" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Update session configs\nclient.sessions.update_configs(\n session_id='session-uuid'\n)\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Update session configs\nawait client.sessions.updateConfigs('session-uuid');\n" } ] }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Update session configs using patch semantics. Only updates keys present in the request. Pass null as value to delete a key. Returns the complete configs after patch.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Patch session configs", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true }, { "description": "PatchSessionConfigs payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.PatchSessionConfigsReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.PatchSessionConfigsResp" } } } ] } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/serializer.Response" } }, "404": { "description": "Session not found", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Patch session configs (adds/updates keys, use None to delete)\nupdated_configs = client.sessions.patch_configs(\n session_id='session-uuid',\n configs={'agent': 'bot2', 'old_key': None} # None deletes the key\n)\nprint(updated_configs) # {'existing_key': 'value', 'agent': 'bot2'}\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Patch session configs (adds/updates keys, use null to delete)\nconst updatedConfigs = await client.sessions.patchConfigs(\n 'session-uuid',\n { agent: 'bot2', old_key: null } // null deletes the key\n);\nconsole.log(updatedConfigs); // { existing_key: 'value', agent: 'bot2' }\n" } ] } }, "/session/{session_id}/copy": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a complete copy of a session with all its messages and tasks. The copied session will be independent and can be modified without affecting the original.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Copy session", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.CopySessionResp" } } } ] } }, "400": { "description": "Invalid session ID", "schema": { "$ref": "#/definitions/serializer.Response" } }, "404": { "description": "Session not found", "schema": { "$ref": "#/definitions/serializer.Response" } }, "413": { "description": "Session exceeds maximum copyable size", "schema": { "$ref": "#/definitions/serializer.Response" } }, "500": { "description": "Failed to copy session", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Copy a session\nresult = client.sessions.copy(session_id='session-uuid')\nprint(f\"Copied session: {result.new_session_id}\")\nprint(f\"Original session: {result.old_session_id}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Copy a session\nconst result = await client.sessions.copy('session-uuid');\nconsole.log(`Copied session: ${result.newSessionId}`);\nconsole.log(`Original session: ${result.oldSessionId}`);\n" } ] } }, "/session/{session_id}/events": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get events for a session with cursor-based pagination.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Get events for session", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true }, { "type": "integer", "description": "Limit of events to return, default 50. Max 200.", "name": "limit", "in": "query" }, { "type": "string", "description": "Cursor for pagination.", "name": "cursor", "in": "query" }, { "type": "boolean", "example": false, "description": "Order by created_at descending if true, ascending if false (default false)", "name": "time_desc", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.ListEventsOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get events for a session\nevents = client.sessions.get_events(session_id, limit=50)\nfor event in events.items:\n print(f\"{event.type}: {event.data}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get events for a session\nconst events = await client.sessions.getEvents(sessionId, { limit: 50 });\nfor (const event of events.items) {\n console.log(`${event.type}: ${JSON.stringify(event.data)}`);\n}\n" } ] }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Add a structured event to a session. Events are stored alongside messages and can be retrieved chronologically.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Add event to session", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true }, { "description": "AddEvent payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.AddEventReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.SessionEvent" } } } ] } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/serializer.Response" } }, "404": { "description": "Session not found", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\nfrom acontext.event import DiskEvent, TextEvent\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Add a disk event\nclient.sessions.add_event(session_id, DiskEvent(disk_id='xxxx', path='/data/report.csv', note='Uploaded report'))\n\n# Add a text event\nclient.sessions.add_event(session_id, TextEvent(text='User switched to dark mode'))\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient, DiskEvent, TextEvent } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Add a disk event\nawait client.sessions.addEvent(sessionId, new DiskEvent({ diskId: 'xxxx', path: '/data/report.csv', note: 'Uploaded report' }));\n\n// Add a text event\nawait client.sessions.addEvent(sessionId, new TextEvent({ text: 'User switched to dark mode' }));\n" } ] } }, "/session/{session_id}/flush": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Flush the session buffer for a given session", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Flush session", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/httpclient.FlagResponse" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Flush session buffer\nresult = client.sessions.flush(session_id='session-uuid')\nprint(result.status)\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Flush session buffer\nconst result = await client.sessions.flush('session-uuid');\nconsole.log(result.status);\n" } ] } }, "/session/{session_id}/messages": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get messages from session. Default format is openai. Can convert to acontext (original), anthropic, or gemini format.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Get messages from session", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true }, { "type": "integer", "description": "Limit of messages to return. Max 200. If limit is 0 or not provided, all messages will be returned. \n\nWARNING!\n Use `limit` only for read-only/display purposes (pagination, viewing). Do NOT use `limit` to truncate messages before sending to LLM as it may cause tool-call and tool-result unpairing issues. Instead, use the `token_limit` edit strategy in `edit_strategies` parameter to safely manage message context size.", "name": "limit", "in": "query" }, { "type": "string", "description": "Cursor for pagination. Use the cursor from the previous response to get the next page.", "name": "cursor", "in": "query" }, { "type": "boolean", "example": true, "description": "Whether to return asset public url, default is true", "name": "with_asset_public_url", "in": "query" }, { "type": "boolean", "example": false, "description": "Whether to include session events in the response, default is false", "name": "with_events", "in": "query" }, { "enum": [ "acontext", "openai", "anthropic", "gemini" ], "type": "string", "description": "Format to convert messages to: acontext (original), openai (default), anthropic, gemini.", "name": "format", "in": "query" }, { "type": "boolean", "example": false, "description": "Order by created_at descending if true, ascending if false (default false)", "name": "time_desc", "in": "query" }, { "type": "string", "example": "[{\"type\":\"remove_tool_result\",\"params\":{\"keep_recent_n_tool_results\":3}}]", "description": "JSON array of edit strategies to apply before format conversion", "name": "edit_strategies", "in": "query" }, { "type": "string", "example": "", "description": "Message ID to pin editing strategies at. When provided, strategies are only applied to messages up to and including this message ID, keeping subsequent messages unchanged. This helps maintain prompt cache stability by preserving a stable prefix. The response will include edit_at_message_id indicating where strategies were applied.", "name": "pin_editing_strategies_at_message", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/converter.GetMessagesOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get messages from session\nmessages = client.sessions.get_messages(\n session_id='session-uuid',\n limit=50,\n format='acontext',\n time_desc=True\n)\nfor message in messages.items:\n print(f\"{message.role}: {message.parts}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get messages from session\nconst messages = await client.sessions.getMessages('session-uuid', {\n limit: 50,\n format: 'acontext',\n timeDesc: true\n});\nfor (const message of messages.items) {\n console.log(`${message.role}: ${JSON.stringify(message.parts)}`);\n}\n" } ] }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Supports JSON and multipart/form-data. In multipart mode: the payload is a JSON string placed in a form field. The format parameter indicates the format of the input message (default: openai, same as GET). The blob field should be a complete message object: for openai, use OpenAI ChatCompletionMessageParam format (with role and content); for anthropic, use Anthropic MessageParam format (with role and content); for acontext (internal), use {role, parts} format. The optional meta field allows attaching user-provided metadata to the message, which can be retrieved via get_messages().metas or updated via patch_message_meta().", "consumes": [ "application/json", "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Store message to session", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true }, { "description": "StoreMessage payload (Content-Type: application/json)", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.StoreMessageReq" } }, { "type": "string", "description": "StoreMessage payload (Content-Type: multipart/form-data)", "name": "payload", "in": "formData" }, { "type": "file", "description": "When uploading files, the field name must correspond to parts[*].file_field.", "name": "file", "in": "formData" } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.Message" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\nfrom acontext.messages import build_acontext_message\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Store a message in OpenAI format with user metadata\nclient.sessions.store_message(\n session_id='session-uuid',\n blob={'role': 'user', 'content': 'Hello!'},\n format='openai',\n meta={'source': 'web', 'request_id': 'abc123'}\n)\n\n# Store a message in Acontext format\nmessage = build_acontext_message(role='user', parts=['Hello!'])\nclient.sessions.store_message(\n session_id='session-uuid',\n blob=message,\n format='acontext'\n)\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient, MessagePart } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Store a message in OpenAI format with user metadata\nawait client.sessions.storeMessage(\n 'session-uuid',\n { role: 'user', content: 'Hello!' },\n { format: 'openai', meta: { source: 'web', request_id: 'abc123' } }\n);\n\n// Store a message in Acontext format\nawait client.sessions.storeMessage(\n 'session-uuid',\n {\n role: 'user',\n parts: [MessagePart.textPart('Hello!')]\n },\n { format: 'acontext' }\n);\n" } ] } }, "/session/{session_id}/messages/{message_id}/meta": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Update message metadata using patch semantics. Only updates keys present in the request. Pass null as value to delete a key.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Patch message metadata", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true }, { "type": "string", "format": "uuid", "description": "Message ID", "name": "message_id", "in": "path", "required": true }, { "description": "PatchMessageMeta payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.PatchMessageMetaReq" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.PatchMessageMetaResp" } } } ] } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/serializer.Response" } }, "404": { "description": "Message not found", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Patch message meta (adds/updates keys, use None to delete)\nupdated_meta = client.sessions.patch_message_meta(\n session_id='session-uuid',\n message_id='message-uuid',\n meta={'status': 'processed', 'old_key': None} # None deletes the key\n)\nprint(updated_meta) # {'existing_key': 'value', 'status': 'processed'}\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Patch message meta (adds/updates keys, use null to delete)\nconst updatedMeta = await client.sessions.patchMessageMeta(\n 'session-uuid',\n 'message-uuid',\n { status: 'processed', old_key: null } // null deletes the key\n);\nconsole.log(updatedMeta); // { existing_key: 'value', status: 'processed' }\n" } ] } }, "/session/{session_id}/observing_status": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns the count of observed, in_process, and pending messages", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Get message observing status for a session", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.MessageObservingStatus" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get message observing status\nresult = client.sessions.messages_observing_status(session_id='session-uuid')\nprint(f\"Observed: {result.observed}, In Process: {result.in_process}, Pending: {result.pending}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get message observing status\nconst result = await client.sessions.messagesObservingStatus('session-uuid');\nconsole.log(`Observed: ${result.observed}, In Process: ${result.in_process}, Pending: ${result.pending}`);\n" } ] } }, "/session/{session_id}/task": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get tasks from session with cursor-based pagination", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "task" ], "summary": "Get tasks from session", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true }, { "type": "integer", "description": "Limit of tasks to return, default 20. Max 200.", "name": "limit", "in": "query" }, { "type": "string", "description": "Cursor for pagination. Use the cursor from the previous response to get the next page.", "name": "cursor", "in": "query" }, { "type": "boolean", "example": false, "description": "Order by created_at descending if true, ascending if false (default false)", "name": "time_desc", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.GetTasksOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get tasks from a session\ntasks = client.sessions.get_tasks(\n session_id='session-uuid',\n limit=20,\n time_desc=False\n)\nprint(f\"Found {len(tasks.items)} tasks\")\nfor task in tasks.items:\n print(f\"Task {task.id}: {task.status}\")\n\n# If there are more tasks, use the cursor for pagination\nif tasks.has_more:\n next_tasks = client.sessions.get_tasks(\n session_id='session-uuid',\n limit=20,\n cursor=tasks.next_cursor\n )\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get tasks from a session\nconst tasks = await client.sessions.getTasks('session-uuid', {\n limit: 20,\n timeDesc: false\n});\nconsole.log(`Found ${tasks.items.length} tasks`);\nfor (const task of tasks.items) {\n console.log(`Task ${task.id}: ${task.status}`);\n}\n\n// If there are more tasks, use the cursor for pagination\nif (tasks.hasMore) {\n const nextTasks = await client.sessions.getTasks('session-uuid', {\n limit: 20,\n cursor: tasks.nextCursor\n });\n}\n" } ] } }, "/session/{session_id}/token_counts": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get total token counts for all text and tool-call parts in a session", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "session" ], "summary": "Get token counts for session", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "session_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.TokenCountsResp" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get token counts\nresult = client.sessions.get_token_counts(session_id='session-uuid')\nprint(f\"Total tokens: {result.total_tokens}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get token counts\nconst result = await client.sessions.getTokenCounts('session-uuid');\nconsole.log(`Total tokens: ${result.total_tokens}`);\n" } ] } }, "/user/ls": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get all users under a project. If limit is not provided or 0, all users will be returned.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "user" ], "summary": "List users", "parameters": [ { "type": "integer", "description": "Limit of users to return. Max 200. If limit is 0 or not provided, all users will be returned.", "name": "limit", "in": "query" }, { "type": "string", "description": "Cursor for pagination. Use the cursor from the previous response to get the next page.", "name": "cursor", "in": "query" }, { "type": "boolean", "example": false, "description": "Order by created_at descending if true, ascending if false (default false)", "name": "time_desc", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.ListUsersOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# List all users\nusers = client.users.list()\nfor user in users.items:\n print(f\"{user.identifier}: {user.id}\")\n\n# List users with pagination\nusers = client.users.list(limit=20, time_desc=True)\nif users.has_more:\n next_users = client.users.list(limit=20, cursor=users.next_cursor)\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// List all users\nconst users = await client.users.list();\nfor (const user of users.items) {\n console.log(`${user.identifier}: ${user.id}`);\n}\n\n// List users with pagination\nconst paginatedUsers = await client.users.list({ limit: 20, timeDesc: true });\nif (paginatedUsers.hasMore) {\n const nextUsers = await client.users.list({ limit: 20, cursor: paginatedUsers.nextCursor });\n}\n" } ] } }, "/user/{identifier}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete a user by identifier and cascade delete all associated resources (Session, Disk, Skill)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "user" ], "summary": "Delete user", "parameters": [ { "type": "string", "description": "User identifier string", "name": "identifier", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/serializer.Response" } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Delete a user and all associated resources\nclient.users.delete('alice@acontext.io')\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Delete a user and all associated resources\nawait client.users.delete('alice@acontext.io');\n" } ] } }, "/user/{identifier}/resources": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get the resource counts (Sessions, Disks, Skills) associated with a user", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "user" ], "summary": "Get user resources", "parameters": [ { "type": "string", "description": "User identifier string", "name": "identifier", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/serializer.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/service.GetUserResourcesOutput" } } } ] } } }, "x-code-samples": [ { "label": "Python", "lang": "python", "source": "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Get user resource counts\nresources = client.users.get_resources('alice@acontext.io')\nprint(f\"Sessions: {resources.counts.sessions_count}\")\nprint(f\"Disks: {resources.counts.disks_count}\")\nprint(f\"Skills: {resources.counts.skills_count}\")\n" }, { "label": "JavaScript", "lang": "javascript", "source": "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Get user resource counts\nconst resources = await client.users.getResources('alice@acontext.io');\nconsole.log(`Sessions: ${resources.counts.sessions_count}`);\nconsole.log(`Disks: ${resources.counts.disks_count}`);\nconsole.log(`Skills: ${resources.counts.skills_count}`);\n" } ] } } }, "definitions": { "converter.GetMessagesOutput": { "type": "object", "properties": { "edit_at_message_id": { "description": "Message ID where edit strategies were applied", "type": "string" }, "events": { "description": "Session events within the messages time window", "type": "array", "items": { "$ref": "#/definitions/model.SessionEvent" } }, "has_more": { "description": "Whether there are more messages", "type": "boolean" }, "ids": { "description": "Message IDs corresponding to items", "type": "array", "items": { "type": "string" } }, "items": { "description": "Messages in the requested format" }, "metas": { "description": "User-provided metadata for each message (same order as items/ids)", "type": "array", "items": { "type": "object", "additionalProperties": true } }, "next_cursor": { "description": "Cursor for pagination", "type": "string" }, "public_urls": { "description": "Asset public URLs (only for acontext format)", "type": "object", "additionalProperties": { "$ref": "#/definitions/service.PublicURL" } }, "this_time_tokens": { "description": "Token count for returned messages", "type": "integer" } } }, "fileparser.FileContent": { "type": "object", "properties": { "raw": { "description": "Raw text content", "type": "string" }, "type": { "description": "\"text\", \"json\", \"csv\", \"code\"", "type": "string" } } }, "handler.AddEventReq": { "type": "object" }, "handler.CopySessionResp": { "type": "object", "properties": { "new_session_id": { "type": "string" }, "old_session_id": { "type": "string" } } }, "handler.CreateDiskReq": { "type": "object", "properties": { "user": { "type": "string", "example": "alice@acontext.io" } } }, "handler.CreateLearningSpaceReq": { "type": "object", "properties": { "meta": { "type": "object" }, "user": { "type": "string", "example": "alice@acontext.io" } } }, "handler.CreateProjectReq": { "type": "object", "properties": { "configs": { "type": "object", "additionalProperties": true } } }, "handler.CreateSessionReq": { "type": "object", "properties": { "configs": { "type": "object", "additionalProperties": true }, "disable_task_tracking": { "type": "boolean", "example": false }, "use_uuid": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "user": { "type": "string", "example": "alice@acontext.io" } } }, "handler.DownloadSkillToSandboxReq": { "type": "object", "required": [ "sandbox_id" ], "properties": { "sandbox_id": { "description": "Target sandbox ID", "type": "string" } } }, "handler.DownloadSkillToSandboxResp": { "type": "object", "properties": { "description": { "description": "Skill description", "type": "string" }, "dir_path": { "description": "Full path to the skill directory in sandbox", "type": "string" }, "name": { "description": "Skill name", "type": "string" }, "success": { "description": "Whether the download was successful", "type": "boolean" } } }, "handler.DownloadToSandboxReq": { "type": "object", "required": [ "file_path", "filename", "sandbox_id", "sandbox_path" ], "properties": { "file_path": { "description": "File path (directory) of the artifact", "type": "string" }, "filename": { "description": "Filename of the artifact", "type": "string" }, "sandbox_id": { "description": "Target sandbox ID", "type": "string" }, "sandbox_path": { "description": "Destination directory in the sandbox", "type": "string" } } }, "handler.DownloadToSandboxResp": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "handler.ExecCommandReq": { "type": "object", "required": [ "command" ], "properties": { "command": { "type": "string" } } }, "handler.GetArtifactResp": { "type": "object", "properties": { "artifact": { "$ref": "#/definitions/model.Artifact" }, "content": { "$ref": "#/definitions/fileparser.FileContent" }, "public_url": { "type": "string" } } }, "handler.IncludeSkillReq": { "type": "object", "required": [ "skill_id" ], "properties": { "skill_id": { "type": "string", "example": "skill-uuid" } } }, "handler.LearnReq": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string", "example": "session-uuid" } } }, "handler.ListArtifactsResp": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "$ref": "#/definitions/model.Artifact" } }, "directories": { "type": "array", "items": { "type": "string" } } } }, "handler.PatchMessageMetaReq": { "type": "object", "required": [ "meta" ], "properties": { "meta": { "type": "object", "additionalProperties": true } } }, "handler.PatchMessageMetaResp": { "type": "object", "properties": { "meta": { "type": "object", "additionalProperties": true } } }, "handler.PatchSessionConfigsReq": { "type": "object", "required": [ "configs" ], "properties": { "configs": { "type": "object", "additionalProperties": true } } }, "handler.PatchSessionConfigsResp": { "type": "object", "properties": { "configs": { "type": "object", "additionalProperties": true } } }, "handler.StoreMessageReq": { "type": "object", "required": [ "blob" ], "properties": { "blob": {}, "format": { "type": "string", "enum": [ "acontext", "openai", "anthropic", "gemini" ], "example": "openai" }, "meta": { "description": "Optional user-provided metadata for the message", "type": "object", "additionalProperties": true } } }, "handler.TokenCountsResp": { "type": "object", "properties": { "total_tokens": { "type": "integer" } } }, "handler.UpdateArtifactReq": { "type": "object", "required": [ "file_path", "meta" ], "properties": { "file_path": { "description": "File path including filename", "type": "string" }, "meta": { "description": "Custom metadata as JSON string", "type": "string" } } }, "handler.UpdateArtifactResp": { "type": "object", "properties": { "artifact": { "$ref": "#/definitions/model.Artifact" } } }, "handler.UpdateLearningSpaceReq": { "type": "object", "required": [ "meta" ], "properties": { "meta": { "type": "object" } } }, "handler.UpdateSessionConfigsReq": { "type": "object", "properties": { "configs": { "type": "object", "additionalProperties": true } } }, "handler.UploadFromSandboxReq": { "type": "object", "required": [ "file_path", "sandbox_filename", "sandbox_id", "sandbox_path" ], "properties": { "file_path": { "description": "Destination directory path on the disk", "type": "string" }, "sandbox_filename": { "description": "Filename in the sandbox", "type": "string" }, "sandbox_id": { "description": "Source sandbox ID", "type": "string" }, "sandbox_path": { "description": "Source directory in the sandbox", "type": "string" } } }, "httpclient.FlagResponse": { "type": "object", "properties": { "errmsg": { "type": "string" }, "status": { "type": "integer" } } }, "httpclient.SandboxCommandOutput": { "type": "object", "properties": { "exit_code": { "type": "integer" }, "stderr": { "type": "string" }, "stdout": { "type": "string" } } }, "httpclient.SandboxRuntimeInfo": { "type": "object", "properties": { "sandbox_created_at": { "type": "string" }, "sandbox_expires_at": { "type": "string" }, "sandbox_id": { "type": "string" }, "sandbox_status": { "type": "string" } } }, "model.AgentSkills": { "type": "object", "properties": { "created_at": { "type": "string" }, "description": { "type": "string" }, "disk_id": { "description": "DiskID references the Disk that stores this skill's files as Artifacts", "type": "string" }, "file_index": { "description": "FileIndex is computed at query time from the Disk's Artifacts, not persisted", "type": "array", "items": { "$ref": "#/definitions/model.FileInfo" } }, "id": { "type": "string" }, "meta": { "type": "object" }, "name": { "description": "Name is not unique - multiple skills can have the same name", "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "string" } } }, "model.Artifact": { "type": "object", "properties": { "created_at": { "type": "string" }, "disk_id": { "type": "string" }, "filename": { "type": "string" }, "meta": { "type": "object" }, "path": { "type": "string" }, "updated_at": { "type": "string" } } }, "model.Disk": { "type": "object", "properties": { "created_at": { "type": "string" }, "id": { "type": "string" }, "project_id": { "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "string" } } }, "model.FileInfo": { "type": "object", "properties": { "mime": { "description": "MIME type of the file", "type": "string" }, "path": { "description": "Relative path from skillName root", "type": "string" } } }, "model.LearningSpace": { "type": "object", "properties": { "created_at": { "type": "string" }, "id": { "type": "string" }, "meta": { "type": "object" }, "updated_at": { "type": "string" }, "user_id": { "type": "string" } } }, "model.LearningSpaceSession": { "type": "object", "properties": { "created_at": { "type": "string" }, "id": { "type": "string" }, "learning_space_id": { "type": "string" }, "session_id": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string" } } }, "model.LearningSpaceSkill": { "type": "object", "properties": { "created_at": { "type": "string" }, "id": { "type": "string" }, "learning_space_id": { "type": "string" }, "skill_id": { "type": "string" } } }, "model.Message": { "type": "object", "properties": { "created_at": { "type": "string" }, "id": { "type": "string" }, "meta": { "type": "object" }, "parent_id": { "type": "string" }, "parts": { "type": "array", "items": { "type": "object" } }, "role": { "type": "string" }, "session_id": { "type": "string" }, "session_task_process_status": { "type": "string" }, "task_id": { "type": "string" }, "updated_at": { "type": "string" } } }, "model.MessageObservingStatus": { "type": "object", "properties": { "in_process": { "type": "integer" }, "observed": { "type": "integer" }, "pending": { "type": "integer" }, "updated_at": { "type": "string" } } }, "model.SandboxLog": { "type": "object", "properties": { "backend_sandbox_id": { "type": "string" }, "backend_type": { "type": "string" }, "created_at": { "type": "string" }, "generated_files": { "type": "array", "items": { "type": "object" } }, "history_commands": { "type": "array", "items": { "type": "object" } }, "id": { "type": "string" }, "project_id": { "type": "string" }, "updated_at": { "type": "string" }, "will_total_alive_seconds": { "type": "integer" } } }, "model.Session": { "type": "object", "properties": { "configs": { "type": "object" }, "created_at": { "type": "string" }, "disable_task_tracking": { "type": "boolean" }, "id": { "type": "string" }, "project_id": { "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "string" } } }, "model.SessionEvent": { "type": "object", "properties": { "created_at": { "type": "string" }, "data": { "type": "object" }, "id": { "type": "string" }, "project_id": { "type": "string" }, "session_id": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" } } }, "model.Task": { "type": "object", "properties": { "created_at": { "type": "string" }, "data": { "$ref": "#/definitions/model.TaskData" }, "id": { "type": "string" }, "is_planning": { "type": "boolean" }, "order": { "type": "integer" }, "project_id": { "type": "string" }, "session_id": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string" } } }, "model.TaskData": { "type": "object", "properties": { "progresses": { "type": "array", "items": { "type": "string" } }, "task_description": { "type": "string" }, "user_preferences": { "type": "array", "items": { "type": "string" } } } }, "model.User": { "type": "object", "properties": { "created_at": { "type": "string" }, "id": { "type": "string" }, "identifier": { "type": "string" }, "project_id": { "type": "string" }, "updated_at": { "type": "string" } } }, "repo.UserResourceCounts": { "type": "object", "properties": { "disks_count": { "type": "integer" }, "sessions_count": { "type": "integer" }, "skills_count": { "type": "integer" } } }, "serializer.Response": { "type": "object", "properties": { "code": { "type": "integer" }, "error": { "type": "string" }, "msg": { "type": "string" } } }, "service.AgentSkillsListItem": { "type": "object", "properties": { "created_at": { "type": "string" }, "description": { "type": "string" }, "file_index": { "type": "array", "items": { "$ref": "#/definitions/model.FileInfo" } }, "id": { "type": "string" }, "meta": { "type": "object", "additionalProperties": true }, "name": { "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "string" } } }, "service.CreateProjectOutput": { "type": "object", "properties": { "project_id": { "type": "string" }, "secret_key": { "type": "string" } } }, "service.GetFileOutput": { "type": "object", "properties": { "content": { "description": "Present if file is text-based and parseable", "allOf": [ { "$ref": "#/definitions/fileparser.FileContent" } ] }, "mime": { "type": "string" }, "path": { "type": "string" }, "url": { "description": "Material URL for binary files (works for both encrypted and non-encrypted)", "type": "string" } } }, "service.GetSandboxLogsOutput": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/model.SandboxLog" } }, "next_cursor": { "type": "string" } } }, "service.GetTasksOutput": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/model.Task" } }, "next_cursor": { "type": "string" } } }, "service.GetUserResourcesOutput": { "type": "object", "properties": { "counts": { "$ref": "#/definitions/repo.UserResourceCounts" } } }, "service.ListAgentSkillsOutput": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/service.AgentSkillsListItem" } }, "next_cursor": { "type": "string" } } }, "service.ListDisksOutput": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/model.Disk" } }, "next_cursor": { "type": "string" } } }, "service.ListEventsOutput": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/model.SessionEvent" } }, "next_cursor": { "type": "string" } } }, "service.ListLearningSpacesOutput": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/model.LearningSpace" } }, "next_cursor": { "type": "string" } } }, "service.ListSessionsOutput": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/model.Session" } }, "next_cursor": { "type": "string" } } }, "service.ListUsersOutput": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/model.User" } }, "next_cursor": { "type": "string" } } }, "service.PublicURL": { "type": "object", "properties": { "expire_at": { "type": "string" }, "url": { "type": "string" } } }, "service.UpdateSecretKeyOutput": { "type": "object", "properties": { "secret_key": { "type": "string" } } } }, "securityDefinitions": { "BearerAuth": { "description": "Project Bearer token (e.g., \"Bearer sk-ac-xxxx\")", "type": "apiKey", "name": "Authorization", "in": "header" } } }