Vega AI conversations and projects

Vega AI conversations can have editable titles, pins and a personal project. Projects supply instructions and shared files to their conversations. Projects belong to one person within a workspace; sharing projects with other members is not available.

In the Vega AI panel

Open Recent conversations (the history button) to search your conversations by title or first question, filter them by project, and use each conversation's menu to rename, pin, move or delete it. Pinned conversations stay at the top.

Choose Projects to create a project, write its instructions, add files, and start a new chat in it. The composer shows the project of the open conversation. Choose Instructions to edit your own instructions and read the workspace's VEGA.md; workspace admins can also edit VEGA.md. If someone saved instructions after you opened them, reload before saving yours.

API

The API prefix is /api/v1/vegaflow/orgs/{org_id}/workspaces/{workspace_id}/vega-ai. These operations require authentication and use permission on vega_ai. Workspace instruction updates additionally require admin permission. Project operations are restricted to their owner.

Find and organize conversations

GET /conversations returns items and, when another page exists, next_cursor. Each page contains up to 50 conversations. Pinned conversations appear first, with the most recent pin first; other conversations appear by most recent question activity. Accepting a question and reaching its terminal state both count as activity.

Use these optional query parameters:

• q: a literal case-insensitive substring, 2–100 characters, matched against the title and the first 500 characters of the first question. Answers, tool results and file contents are not searched.
• project_id: a project UUID, or none for conversations outside a project.
• cursor: the opaque next_cursor from the previous page. Keep the same search and project filter on subsequent requests.

A conversation includes title, title_source (derived, generated or user), pinned, nullable pinned_at, last_activity_at, nullable project_id and resource_version, alongside its existing identity and approval settings. After the first answer, Vega AI may replace the derived title with a short generated title. Generation happens asynchronously and never overwrites a user title.

PATCH /conversations/{id} accepts any combination of title, pinned, approval_mode and project_id. Send If-Match with the current resource version, for example If-Match: "3". Titles are trimmed and must contain 1–120 characters without control characters. Set project_id to a project UUID to move a conversation, or null to move it out. A person can pin at most 20 conversations per workspace; exceeding that limit returns 409 CONVERSATION_PIN_LIMIT. A stale version returns 412 RESOURCE_VERSION_MISMATCH; fetch the current resource before retrying.

DELETE /conversations/{id} immediately hides an owned conversation, cancels its active question and expires pending approvals. If-Match is optional. Success returns 204, including repeated deletion while the deletion record remains. There is no undelete operation. Conversation content and files are scheduled for cleanup within the earlier of the existing retention expiry and 24 hours; storage failures may delay physical cleanup. Previously issued download URLs can remain valid for up to five minutes.

Personal projects

GET /projects returns all owned projects in name order with conversation_count and file_count. Create one with POST /projects and a body such as {"name":"Quarterly analysis","description":"Revenue investigation"}. Creation returns 201. Names are trimmed, 1–100 characters and unique ignoring case within the person's workspace. Descriptions have at most 500 characters. The limit is 100 projects per person per workspace.

GET /projects/{id} returns a project and its ETag. PATCH /projects/{id} changes name, description or both and requires If-Match. Duplicate names return 409 PROJECT_NAME_EXISTS, and the project limit returns 409 PROJECT_LIMIT. Stale updates return 412 RESOURCE_VERSION_MISMATCH.

POST /conversations accepts an optional project_id when creating a conversation. A project must belong to the caller in the same workspace. Deleting a project with DELETE /projects/{id} returns 204, moves its conversations outside the project, and schedules its files for cleanup. It does not delete the conversations.

Reusable instructions

Instruction documents are available at:

• GET/PUT /instructions/workspace: workspace VEGA.md, at most 32 KiB. Reading requires use; writing requires admin on vega_ai.
• GET/PUT /projects/{id}/instructions: the owned project's instructions, at most 16 KiB.
• GET/PUT /instructions/personal: the caller's personal instructions, at most 8 KiB.

Responses contain version, body, updated_at and updated_by. An absent document has version 0, an empty body, null update time and an empty updater. PUT accepts {"body":"instruction text"} and requires a quoted instruction version in If-Match, including If-Match: "0" to create. A stale version returns 412; a non-admin workspace write returns 403. Limits count UTF-8 bytes. An empty body writes a new version with no effective instructions.

The order is platform rules, agent definition, workspace VEGA.md, project, then personal instructions. Later instructions cannot authorize bypassing platform safety or approval checks. Each question retains the instruction versions it used. Moving a conversation changes its project instruction layer from the next question onward.

Shared project files

Use the existing POST /attachments staging API and presigned upload URLs, then send {"attachment_ids":["uuid"]} to POST /projects/{id}/files. A request promotes 1–20 distinct, single-use upload receipts and returns 201 with an items array of added files. Upload receipts must belong to the caller. Use GET /projects/{id}/files to list active files and DELETE /projects/{id}/files/{file_id} to remove one.

A project can contain 20 files totaling 100 MiB, with at most 25 MiB per file. Supported formats are PNG, JPEG, WebP, GIF, PDF, CSV, XLSX, JSON, TXT and MD. Exceeding the project quota returns 409 PROJECT_FILE_LIMIT. Unknown or foreign receipts return 404 ATTACHMENT_NOT_FOUND; expired receipts return 410 ATTACHMENT_EXPIRED; reused receipts return 409 ATTACHMENT_ALREADY_USED.

GET /projects/{id}/files/{file_id}/content returns a 303 redirect to a five-minute download URL. Optional inline=1 requests inline viewing subject to the existing file-type restrictions.

Every new run in the project sees current file names, types, sizes and bounded text previews. Images and PDFs are listed without being attached as model media. Code mode reads these files under /project/<name>, separately from conversation files under /input. Both mounts are read-only and share a 50-file, 256 MiB per-call limit: project files take priority, then the newest conversation files. Removed files disappear from later runs. Project files are untrusted data and can cause an external write to require approval even in auto mode.