{"openapi":"3.1.0","info":{"title":"NEOMIND Agent Access API","version":"1.0.0","description":"User-delegated, workspace-scoped tools. Tokens never authorize ordinary NEOMIND user endpoints. Flow for an assistant that can send POST requests: (1) POST /agent-access/device-authorizations, (2) show the user 'message' / 'verification_uri_complete' and wait for approval, (3) POST /agent-access/token every 'interval' seconds until it answers 200, then call GET /agent/projects with 'Authorization: Bearer <access_token>'. An assistant that can only open URLs cannot use this flow: it reads https://neomind.kz/ai and asks the user for a read-only access link instead. To fill in or update a project card, request scopes projects:read, passport:read, projects:draft:create, projects:draft:write and passport:draft:write (projects:draft:write lets the assistant fix the basic fields of a draft: title, description, type, industry, direction, region, stage, TRL, start date); the field reference is GET /agent-access/card-fields; saving never publishes or submits anything. A cohort curator's assistant may request accelerator:roster:draft: GET /agent/accelerator/cohorts lists the cohorts the user curates and POST /agent/accelerator/roster-drafts hands one of them a list of projects as a DRAFT the curator reviews and enrols from himself -- nothing is ever enrolled by the assistant. To PROPOSE values for fields of a project the user may edit, request projects:suggest: GET /agent/projects/{projectId}/field-suggestion-targets lists the fields, POST /agent/projects/{projectId}/field-suggestions leaves each value as a pending suggestion the user accepts or rejects in NEOMIND -- nothing is written to the project."},"servers":[{"url":"https://neomind.kz/v1"}],"components":{"securitySchemes":{"agentBearer":{"type":"http","scheme":"bearer","bearerFormat":"opaque"}}},"paths":{"/agent-access/card-fields":{"get":{"operationId":"getProjectCardFields","description":"Public and static. Every field of a project card (the draft summary and the passport sections) with its type, allowed values and limits. Read it before writing a card.","responses":{"200":{"description":"Field reference"}}}},"/agent-access/device-authorizations":{"post":{"operationId":"startAgentDeviceAuthorization","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["client_id","scopes"],"properties":{"client_id":{"type":"string","const":"neomind-external-agent"},"scopes":{"type":"array","minItems":1,"maxItems":9,"uniqueItems":true,"items":{"type":"string","enum":["projects:read","projects:draft:create","projects:draft:write","passport:read","passport:draft:write","monitoring:read","accelerator:roster:draft","portfolio:read","projects:suggest"]}}}}}}},"responses":{"200":{"description":"Device authorization created. Show 'message' (or 'verification_uri_complete') to the user.","content":{"application/json":{"schema":{"type":"object","required":["device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval","message"],"properties":{"device_code":{"type":"string","description":"Secret for polling the token endpoint. Never show it to the user."},"user_code":{"type":"string","pattern":"^[A-Z2-9]{4}-[A-Z2-9]{4}-[A-Z2-9]{4}$"},"verification_uri":{"type":"string","format":"uri"},"verification_uri_complete":{"type":"string","format":"uri","description":"Show this link to the user."},"expires_in":{"type":"integer","description":"Seconds the device code stays valid (600)."},"interval":{"type":"integer","description":"Minimum seconds between token polls."},"message":{"type":"string","description":"Ready sentence for the user, Russian followed by English (RFC 8628 style)."},"message_ru":{"type":"string"},"message_en":{"type":"string"}}}}}},"400":{"description":"Invalid client_id or scopes","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string"}}}}}},"429":{"description":"Temporarily rate limited"}}}},"/agent-access/token":{"post":{"operationId":"exchangeAgentToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["grant_type","client_id","device_code"],"properties":{"grant_type":{"type":"string","const":"urn:ietf:params:oauth:grant-type:device_code"},"client_id":{"type":"string","const":"neomind-external-agent"},"device_code":{"type":"string","minLength":32,"maxLength":200}}},{"type":"object","additionalProperties":false,"required":["grant_type","client_id","refresh_token"],"properties":{"grant_type":{"type":"string","const":"refresh_token"},"client_id":{"type":"string","const":"neomind-external-agent"},"refresh_token":{"type":"string","minLength":32,"maxLength":200}}}]}}}},"description":"While the user has not approved yet the endpoint answers HTTP 400 with {\"error\":\"authorization_pending\"}: keep polling every 'interval' seconds. On slow_down add 5 seconds to the interval.","responses":{"200":{"description":"Opaque access token (about 15 minutes) and a rotating refresh token","content":{"application/json":{"schema":{"type":"object","required":["access_token","token_type","expires_in","refresh_token","scope"],"properties":{"access_token":{"type":"string","description":"Opaque, prefix nma_at_. Send as 'Authorization: Bearer <access_token>'."},"token_type":{"type":"string","const":"Bearer"},"expires_in":{"type":"integer","description":"Seconds until the access token expires (about 900)."},"refresh_token":{"type":"string","description":"Opaque, prefix nma_rt_. Single use: every refresh returns a new one."},"refresh_token_expires_in":{"type":"integer"},"scope":{"type":"string","description":"Space-separated scopes the user approved."}}}}}},"400":{"description":"OAuth error. Always HTTP 400 with an 'error' code.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["authorization_pending","slow_down","expired_token","access_denied","invalid_grant","invalid_request"],"description":"authorization_pending: the user has not approved yet, keep polling. slow_down: poll less often. expired_token: the device code expired, start again. access_denied: the user refused. invalid_grant: unknown, used or revoked code or refresh token. invalid_request: malformed request."}}}}}}}}},"/agent/projects":{"get":{"operationId":"listMyProjects","security":[{"agentBearer":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":160}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":500}}],"description":"Requires scope projects:read. Pass pageInfo.nextCursor as 'cursor' to get the next page.","responses":{"200":{"description":"Projects the user can see in the approved workspace","content":{"application/json":{"schema":{"type":"object","required":["items","pageInfo"],"properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"title":{"type":"string"},"shortDescription":{"type":["string","null"]},"projectType":{"type":"string","enum":["STARTUP","SCIENTIFIC","COMMERCIALIZATION","TECHNOLOGICAL","SOCIAL_IMPACT","INVESTMENT","OTHER"]},"industry":{"type":["string","null"]},"direction":{"type":["string","null"]},"region":{"type":["string","null"]},"stage":{"type":["string","null"],"enum":["IDEA","RESEARCH","PROTOTYPE","PILOT","MARKET","SCALING",null]},"status":{"type":"string","description":"Lifecycle status, for example DRAFT or PUBLISHED."},"trl":{"type":["integer","null"],"minimum":1,"maximum":9},"isPublic":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"owner":{"type":["object","null"],"description":"Id and display name of the project owner."},"projectLead":{"type":["object","null"]},"passport":{"type":"object","properties":{"completionStatus":{"type":"string"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"baseline":{"type":["object","null"],"properties":{"id":{"type":"string"},"version":{"type":"integer"},"confirmedAt":{"type":"string","format":"date-time"}}},"monitoring":{"type":"object","properties":{"latestCheckpoint":{"type":["object","null"]},"checkpointCount":{"type":"integer"}}},"counts":{"type":"object","additionalProperties":{"type":"integer"}}}}},"pageInfo":{"type":"object","required":["limit","hasMore","nextCursor"],"properties":{"limit":{"type":"integer"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"description":"Pass as the 'cursor' query parameter to fetch the next page."}}}}}}}},"401":{"description":"Missing, expired or revoked bearer token"},"403":{"description":"Scope missing (code AGENT_SCOPE_REQUIRED)"}}}},"/agent/projects/{projectId}/status":{"get":{"operationId":"getProjectStatus","security":[{"agentBearer":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success"}}}},"/agent/projects/{projectId}/readiness":{"get":{"operationId":"getProjectReadiness","security":[{"agentBearer":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success"}}}},"/agent/projects/{projectId}/passport":{"get":{"operationId":"getProjectPassport","security":[{"agentBearer":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success"}}}},"/agent/projects/drafts":{"post":{"operationId":"createProjectDraft","security":[{"agentBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["creationSessionId","title","shortDescription","projectType"],"properties":{"creationSessionId":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":500},"shortDescription":{"type":"string","maxLength":4000},"projectType":{"type":"string","enum":["STARTUP","SCIENTIFIC","COMMERCIALIZATION","TECHNOLOGICAL","SOCIAL_IMPACT","INVESTMENT","OTHER"]},"industry":{"type":"string","maxLength":180},"direction":{"type":"string","maxLength":180},"region":{"type":"string","maxLength":120},"stage":{"type":"string","enum":["IDEA","RESEARCH","PROTOTYPE","PILOT","MARKET","SCALING"]},"trl":{"type":"integer","minimum":1,"maximum":9}}}}}},"responses":{"201":{"description":"Private draft created"}}}},"/agent/projects/{projectId}/draft":{"patch":{"operationId":"updateProjectDraft","description":"Needs scope projects:draft:write. Changes the basic fields of a private DRAFT project the user may edit. 409 AGENT_PROJECT_NOT_DRAFT / AGENT_PROJECT_PUBLIC / AGENT_PROJECT_PUBLICATION_PENDING when the project is not a plain private draft (it is public, shows a teaser, has left the draft status or waits for a curator's approval). Unknown fields are rejected. It never changes the status, publication, the public address, the owner or the team.","security":[{"agentBearer":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"title":{"type":"string","minLength":1,"maxLength":500},"shortDescription":{"type":"string","minLength":1,"maxLength":4000},"projectType":{"type":"string","enum":["STARTUP","SCIENTIFIC","COMMERCIALIZATION","TECHNOLOGICAL","SOCIAL_IMPACT","INVESTMENT","OTHER"]},"industry":{"type":["string","null"],"maxLength":180},"direction":{"type":["string","null"],"maxLength":180},"region":{"type":["string","null"],"maxLength":120},"stage":{"type":"string","enum":["IDEA","RESEARCH","PROTOTYPE","PILOT","MARKET","SCALING"]},"trl":{"type":["integer","null"],"minimum":1,"maximum":9},"startDate":{"type":"string","pattern":"^\\d{4}(-\\d{2}(-\\d{2})?)?$","description":"YYYY, YYYY-MM or YYYY-MM-DD; a past or present date."}}}}}},"responses":{"200":{"description":"Draft card updated"}}}},"/agent/projects/{projectId}/passport/section":{"patch":{"operationId":"updateProjectPassportSection","security":[{"agentBearer":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["section","value"],"properties":{"section":{"type":"string","enum":["common","ownership","rntd","market","technology","product","economics","team"]},"value":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Passport section updated"}}}},"/agent/projects/{projectId}/checkpoints":{"get":{"operationId":"listMonitoringCheckpoints","security":[{"agentBearer":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success"}}}},"/agent/accelerator/cohorts":{"get":{"operationId":"listMyCohorts","description":"Needs scope accelerator:roster:draft. The accelerator cohorts the user curates (every cohort of the organisation for an administrator): id, name, start and end date.","security":[{"agentBearer":[]}],"responses":{"200":{"description":"Success"}}}},"/agent/accelerator/roster-drafts":{"post":{"operationId":"proposeCohortRoster","description":"Needs scope accelerator:roster:draft. Saves the user's list of projects for one of his cohorts as a DRAFT for him to review; it never enrols. The curator opens it in NEOMIND (Accelerator -> the cohort -> \"Черновики списков от ИИ\"), checks the matches and enrols the projects he ticks. 403 ACCELERATOR_ACCESS_DENIED when the user is not the cohort's curator or an administrator; 400 ACCELERATOR_ROSTER_DRAFT_EMPTY / ACCELERATOR_ROSTER_TOO_MANY_LINES (over 300 lines) / ACCELERATOR_ROSTER_DRAFT_LIMIT_REACHED (20 open drafts). A retry with the same requestKey returns the same draft.","security":[{"agentBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["cohortId","text","requestKey"],"properties":{"cohortId":{"type":"string","format":"uuid"},"text":{"type":"string","minLength":1,"maxLength":120000,"description":"One project per line: the title, the founder's name or e-mail (cells may be separated by tabs, ; or |)."},"requestKey":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Roster draft saved for the curator's review"}}}},"/agent/projects/{projectId}/field-suggestion-targets":{"get":{"operationId":"listFieldSuggestionTargets","description":"Needs scope projects:suggest and a project the user may edit. The fields you may propose values for (fieldKey, labels, kind, maxChars, hint) and whether each is filled now. 403 when the user may not edit the project or the organisation's AI policy allows no AI.","security":[{"agentBearer":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Proposable fields"}}}},"/agent/projects/{projectId}/field-suggestions":{"post":{"operationId":"proposeFieldValues","description":"Needs scope projects:suggest. PROPOSES values: each one becomes a pending suggestion inside its field that the user accepts or rejects in NEOMIND (it replaces their earlier pending one for that field); nothing is written to the project. Per item: proposed (suggestionId, fieldUrl) or refused (code, reason). At most 8 per call; 429 AGENT_SUGGESTIONS_RATE_LIMITED over 30 per hour per connection.","security":[{"agentBearer":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["proposals"],"properties":{"proposals":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"object","additionalProperties":false,"required":["fieldKey","proposedText"],"properties":{"fieldKey":{"type":"string","enum":["card.shortDescription","common.goal","common.problem","common.solution","common.uniqueness","common.keywords","common.city","market.targetSegment","market.advantages","market.tam","market.sam","market.som","market.potentialClients","technology.approach","product.functionality","product.targetAudience","product.mau","product.pilotsCount","team.competencies","team.teamSize"]},"proposedText":{"type":"string","minLength":1,"maxLength":4000,"description":"Plain text within the field's maxChars; a list as comma-separated items; a number as digits only."}}}}}}}}},"responses":{"200":{"description":"Proposals checked and left for the user's review"}}}},"/agent/mcp":{"post":{"operationId":"mcp","security":[{"agentBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"method":{"type":"string","maxLength":80},"params":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"MCP JSON-RPC response"}}}}}}