{ "openapi": "3.1.0", "info": { "title": "Achieve Aims Agent API", "version": "1.0.0", "description": "Organize explicitly assigned goals. Create credentials in the signed-in Agent connections screen. Authentication grants access to selected unencrypted goals only. The app does not host agent execution." }, "servers": [ { "url": "https://www.achieveaims.com" } ], "security": [ { "agentKey": [] } ], "paths": { "/api/v1/goals": { "get": { "operationId": "listGoals", "summary": "List assigned goals", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } ], "responses": { "200": { "description": "Up to 50 goals; follow nextCursor until null.", "content": { "application/json": { "schema": { "type": "object", "properties": { "goals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "order": { "type": "number" } } } }, "nextCursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid JSON, command, ID, or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential invalid, expired, or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Read-only connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Goal unavailable or outside the credential scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version, idempotency, or capacity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid work transition, dependency, or size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "120 requests per key per minute exceeded; retry next minute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/today": { "get": { "operationId": "readToday", "summary": "Read the next work for up to 50 active assigned goals", "responses": { "200": { "description": "Up to three open items per goal, sorted by current work and priority.", "content": { "application/json": { "schema": { "type": "object", "properties": { "goals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "successCriteria": { "type": "string" }, "handoff": { "anyOf": [ { "type": "object", "properties": { "summary": { "type": "string" }, "nextAction": { "type": "string" }, "actor": { "type": "object", "properties": { "type": { "enum": [ "human", "agent" ] }, "id": { "type": "string" }, "name": { "type": "string" } } }, "updatedAt": { "type": "string" } } }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "successCriteria": { "type": "string" }, "priority": { "enum": [ "low", "normal", "high" ] }, "status": { "enum": [ "planned", "in_progress", "blocked", "done", "cancelled" ] }, "blocker": { "type": "string" }, "dependsOn": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "enum": [ "note", "evidence" ] }, "text": { "type": "string" }, "actor": { "type": "object", "properties": { "type": { "enum": [ "human", "agent" ] }, "id": { "type": "string" }, "name": { "type": "string" } } }, "createdAt": { "type": "string" } } } }, "createdBy": { "type": "object", "properties": { "type": { "enum": [ "human", "agent" ] }, "id": { "type": "string" }, "name": { "type": "string" } } }, "updatedBy": { "type": "object", "properties": { "type": { "enum": [ "human", "agent" ] }, "id": { "type": "string" }, "name": { "type": "string" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } }, "openCount": { "type": "integer" }, "completedCount": { "type": "integer" }, "checklistRemaining": { "type": "integer" } } } } } } } } }, "400": { "description": "Invalid JSON, command, ID, or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential invalid, expired, or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Read-only connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Goal unavailable or outside the credential scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version, idempotency, or capacity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid work transition, dependency, or size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "120 requests per key per minute exceeded; retry next minute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/goals/{goalId}/workspace": { "parameters": [ { "name": "goalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } ], "get": { "operationId": "readGoalWorkspace", "summary": "Read goal context, current work, and latest handoff", "responses": { "200": { "description": "Resume from this workspace before writing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "goal": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "specification": {}, "status": { "type": "string" }, "actionItems": { "type": "array", "items": {} } } }, "workspace": { "$ref": "#/components/schemas/Workspace" } } } } } }, "400": { "description": "Invalid JSON, command, ID, or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential invalid, expired, or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Read-only connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Goal unavailable or outside the credential scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version, idempotency, or capacity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid work transition, dependency, or size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "120 requests per key per minute exceeded; retry next minute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateGoalWorkspace", "summary": "Update shared work; requires write permission", "description": "Reuse the identical command and operationId after a lost response. For version_conflict, read and reconcile before using a new ID. Evidence and completed dependencies are required before reporting an item done. This does not complete the parent goal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Command" }, "example": { "version": 0, "operationId": "5c54ec6a-4ea5-4ddb-93bc-082cb45c40dc", "operation": { "type": "handoff", "summary": "Reviewed the goal.", "nextAction": "Define the first work item." } } } } }, "responses": { "200": { "description": "Updated workspace, or a safe replay of an already-applied command.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "replayed": { "type": "boolean" } } } } } }, "400": { "description": "Invalid JSON, command, ID, or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credential invalid, expired, or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Read-only connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Goal unavailable or outside the credential scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version, idempotency, or capacity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid work transition, dependency, or size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "120 requests per key per minute exceeded; retry next minute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "agentKey": { "type": "http", "scheme": "bearer", "description": "An aag_ credential created by the owner. Never place it in a URL." } }, "schemas": { "Command": { "type": "object", "properties": { "operationId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 0 }, "operation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "create_item" }, "item": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 4000, "default": "" }, "successCriteria": { "type": "string", "maxLength": 2000, "default": "" }, "priority": { "type": "string", "enum": [ "low", "normal", "high" ], "default": "normal" }, "dependsOn": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "default": [] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "required": [ "type", "item" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "update_item" }, "itemId": { "type": "string", "format": "uuid" }, "changes": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 4000 }, "successCriteria": { "type": "string", "maxLength": 2000 }, "status": { "type": "string", "enum": [ "planned", "in_progress", "blocked", "done", "cancelled" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high" ] }, "blocker": { "type": "string", "maxLength": 2000 }, "dependsOn": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, "additionalProperties": false } }, "required": [ "type", "itemId", "changes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "add_note" }, "itemId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "note", "evidence" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "type", "itemId", "kind", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "handoff" }, "summary": { "type": "string", "minLength": 1, "maxLength": 4000 }, "nextAction": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "type", "summary", "nextAction" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "set_criteria" }, "successCriteria": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "type", "successCriteria" ], "additionalProperties": false } ] } }, "required": [ "operationId", "version", "operation" ], "additionalProperties": false }, "Workspace": { "type": "object", "properties": { "_id": { "type": "string" }, "version": { "type": "integer", "minimum": 0 }, "successCriteria": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "successCriteria": { "type": "string" }, "priority": { "enum": [ "low", "normal", "high" ] }, "status": { "enum": [ "planned", "in_progress", "blocked", "done", "cancelled" ] }, "blocker": { "type": "string" }, "dependsOn": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "enum": [ "note", "evidence" ] }, "text": { "type": "string" }, "actor": { "type": "object", "properties": { "type": { "enum": [ "human", "agent" ] }, "id": { "type": "string" }, "name": { "type": "string" } } }, "createdAt": { "type": "string" } } } }, "createdBy": { "type": "object", "properties": { "type": { "enum": [ "human", "agent" ] }, "id": { "type": "string" }, "name": { "type": "string" } } }, "updatedBy": { "type": "object", "properties": { "type": { "enum": [ "human", "agent" ] }, "id": { "type": "string" }, "name": { "type": "string" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } }, "handoff": { "anyOf": [ { "type": "object", "properties": { "summary": { "type": "string" }, "nextAction": { "type": "string" }, "actor": { "type": "object", "properties": { "type": { "enum": [ "human", "agent" ] }, "id": { "type": "string" }, "name": { "type": "string" } } }, "updatedAt": { "type": "string" } } }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "itemId": { "type": "string" }, "actor": { "type": "object", "properties": { "type": { "enum": [ "human", "agent" ] }, "id": { "type": "string" }, "name": { "type": "string" } } }, "createdAt": { "type": "string" } } } }, "updatedAt": { "type": "string" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }