Workspaces And Artifacts

Workspaces are standing context. Artifacts are produced evidence.

That distinction is central to the platform API. A workspace can exist before any workflow runs. Artifacts only appear after work produces something worth recording.

Main Routes

• POST /api/v1/workspaces
• GET /api/v1/workspaces
• GET /api/v1/workspaces/:id
• PATCH /api/v1/workspaces/:id
• GET /api/v1/workspaces/:id/timeline
• GET /api/v1/workspaces/:id/spec
• PUT /api/v1/workspaces/:id/spec
• PATCH /api/v1/workspaces/:id/memory
• GET /api/v1/workspaces/:id/files
• POST /api/v1/workspaces/:id/files
• GET /api/v1/workspaces/:id/artifacts
• POST /api/v1/workspaces/:id/verify-git-access

Create Workspace

POST /api/v1/workspaces

Scope: admin

Request body

{
  "name": "Platform",
  "slug": "platform",
  "description": "Workspace for platform API and dashboard work.",
  "repository_url": "https://github.com/agirunner/agirunner-platform",
  "settings": {
    "storage": {
      "type": "git_remote"
    }
  },
  "memory": {
    "domain": "platform"
  }
}

Workspace fields

Field	Contract	Meaning
name	string	Human-readable workspace name shown in platform surfaces.
slug	string	Stable short identifier for URLs and operator references.
description	string	Purpose and ownership context for the workspace.
repository_url	URL string	Optional upstream repository the workspace tracks.
settings	structured object	Durable workspace configuration such as storage, repository, or runtime-related settings.
memory	arbitrary JSON object	Sticky key/value memory owned by the workspace itself rather than by one workflow run.

Response

{
  "data": {
    "id": "22222222-2222-2222-2222-222222222222",
    "name": "Platform",
    "slug": "platform",
    "description": "Workspace for platform API and dashboard work.",
    "repository_url": "https://github.com/agirunner/agirunner-platform",
    "settings": {
      "storage": {
        "type": "git_remote"
      }
    },
    "memory": {
      "domain": "platform"
    },
    "created_at": "2026-03-31T18:55:00.000Z",
    "updated_at": "2026-03-31T18:55:00.000Z"
  }
}

List Workspaces

GET /api/v1/workspaces

Scope: agent

Query parameters

• q
• is_active
• page
• per_page

Response shape

{
  "data": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "Platform",
      "slug": "platform",
      "is_active": true,
      "summary": {
        "workflow_count": 4,
        "open_workflow_count": 1
      }
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20,
    "pages": 1
  }
}

Update Workspace

PATCH /api/v1/workspaces/:id

Scope: admin

Patch fields can include:

• name
• slug
• description
• repository_url
• settings
• is_active

At least one field is required.

Verify Git Access

POST /api/v1/workspaces/:id/verify-git-access

Scope: admin

Request body

{
  "repository_url": "https://github.com/agirunner/agirunner-platform",
  "default_branch": "main",
  "git_token_mode": "preserve"
}

If git_token_mode is replace, git_token is required.

Git verification fields

Field	Contract	Meaning
repository_url	URL string	Repository URL the platform should test access against.
default_branch	string	Optional branch hint for verification and repository introspection.
git_token_mode	enum	Whether to preserve the current token, replace it for this check, or clear it.
git_token	opaque	Token value only used when git_token_mode=replace.

Response

The result is a verification packet describing whether the platform can access the configured repository with the current workspace settings.

Workspace Memory

Patch memory

PATCH /api/v1/workspaces/:id/memory

Scope: agent or admin

Request body:

{
  "key": "release-policy",
  "value": {
    "owner": "platform-team"
  }
}

Memory patch fields

Field	Contract	Meaning
key	string	Workspace memory slot to write.
value	arbitrary JSON value	Arbitrary JSON payload stored under that memory key.

Delete memory key

DELETE /api/v1/workspaces/:id/memory/:key

Scope: agent or admin

Both routes return the updated workspace record.

Workspace Spec

Read spec

GET /api/v1/workspaces/:id/spec

Scope: agent

Optional query:

• version

Replace spec

PUT /api/v1/workspaces/:id/spec

Scope: admin

Request body:

{
  "resources": {},
  "documents": {},
  "tools": {},
  "config": {},
  "instructions": {}
}

File upload fields

Field	Contract	Meaning
file_name	string	Stored filename presented back to operators and runtimes.
content_base64	base64 string	Base64-encoded file content.
content_type	string	Optional MIME type hint for previews and downloads.
description	string	Optional operator-facing explanation of why the file matters.
key	string	Optional stable logical key. If omitted in batch upload, the platform derives one from the filename.

The spec acts as the durable, structured contract for workspace-owned resources and instructions.

Files

List files

GET /api/v1/workspaces/:id/files

Scope: agent

Upload one file

POST /api/v1/workspaces/:id/files

Scope: admin

Request body:

{
  "file_name": "release-context.md",
  "content_base64": "IyBSZWxlYXNlIGNvbnRleHQK",
  "content_type": "text/markdown",
  "description": "Operator-provided release context."
}

Upload batch

POST /api/v1/workspaces/:id/files/batch

Scope: admin

Request body:

{
  "files": [
    {
      "file_name": "release-context.md",
      "content_base64": "IyBSZWxlYXNlIGNvbnRleHQK"
    }
  ]
}

Download content

GET /api/v1/workspaces/:id/files/:fileId/content

Scope: agent

Returns the raw file bytes with preview headers, not a JSON envelope.

Artifact Explorer

GET /api/v1/workspaces/:id/artifacts

Scope: agent

Query parameters

• q
• workflow_id
• work_item_id
• task_id
• stage_name
• role
• content_type
• preview_mode
• created_from
• created_to
• sort
• page
• per_page

Response shape

The route returns a paginated explorer packet for produced evidence files, not just the raw workspace file list.

Planning Workflow

POST /api/v1/workspaces/:id/planning-workflow

Scope: admin

Request body:

{
  "brief": "Survey the workspace and propose a staged delivery plan.",
  "name": "Workspace planning run"
}

Response:

Returns the created workflow record in { "data": ... }.