Skip to content
General Augment Docs

Get Desired State

GET
/api/v3/projects/{project_id}/desired-state
curl --request GET \
  --url https://example.com/api/v3/projects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/desired-state

Return one server-normalized source head for both equal clients.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
project_id
required
Project Id
string format: uuid

Header Parameters

Section titled “Header Parameters”
X-Admin-Key
Any of:
string

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
DesiredStateSnapshotResponseV3

Exact source head plus the normalized dashboard projection.

object
api_version
Api Version
string
default: genaug.desired-state/v3
Allowed value: genaug.desired-state/v3
assets
Assets
Array<object>
ProjectSourceAssetV3

One source asset supplied with a v3 desired-state bundle.

object
content
required
Content
string
<= 2000000 characters
content_type
Content Type
string
default: text/plain; charset=utf-8 >= 1 characters <= 120 characters
kind
required
Kind
string
Allowed values: soul skill openapi mcp schema
path
required
Path
string
>= 1 characters <= 240 characters
sha256
Any of:
string
/^[0-9a-f]{64}$/
document
required
ProjectConfigV3

The complete secret-free desired state for one General Augment Project.

object
agents
Agents
Array<object>
ProjectAgentV3

Agent behavior plus explicit grants from Project-owned catalogs.

object
capabilities
Capabilities
Array<string>
connections
Connections
Array<string>
delegations
Delegations
Array<object>
AgentDelegationV3

Reviewed edge to another Agent in the same Project.

object
mode
Mode
string
default: as_tool
Allowed values: as_tool handoff
to
required
To
string
>= 1 characters <= 80 characters
display_name
Any of:
string
>= 1 characters <= 200 characters
entry
Entry
boolean
guardrails
AgentGuardrailsV3

Optional Agent-specific guardrail narrowing.

object
persist_history
Any of:
boolean
require_approval_for_write
Any of:
boolean
strict_pii_filtering
Any of:
boolean
limits
AgentLimitsV3

Optional Agent-specific narrowing of the Project policy ceiling.

object
max_tool_calls_per_turn
Any of:
integer
>= 1 <= 100
max_turn_seconds
Any of:
integer
>= 1 <= 900
messages_per_user_per_minute
Any of:
integer
>= 1 <= 10000
memory
Memory
object
key
additional properties
string
Allowed values: read read_write
model
Model
object
key
additional properties
string
name
required
Name
string
>= 1 characters <= 80 characters
purpose
required
Purpose
string
>= 1 characters <= 1000 characters
skills
Skills
Array<string>
soul
required
Soul
string
>= 1 characters <= 240 characters
apiVersion
required
Apiversion
string
Allowed value: genaug/v3
capabilities
Capabilities
object
key
additional properties
CapabilityV3

One Agent-grantable verb backed by a reviewed Project integration.

object
credential
Any of:
string
description
required
Description
string
>= 1 characters <= 500 characters
endpoint
Any of:
string
>= 1 characters <= 2000 characters
input_schema
Input Schema
object
key
additional properties
any
kind
required
Kind
string
Allowed values: builtin openapi mcp direct_app
method
Any of:
string
Allowed values: GET POST PUT PATCH DELETE
operation
Any of:
string
>= 1 characters <= 240 characters
output_schema
Output Schema
object
key
additional properties
any
risk
Risk
string
default: read
Allowed values: read write destructive
source_asset
Any of:
string
>= 1 characters <= 240 characters
tool_id
Any of:
string
>= 1 characters <= 200 characters
transport
Any of:
string
Allowed values: streamable_http sse
url
Any of:
string
>= 1 characters <= 2000 characters
connections
Connections
object
key
additional properties
ConnectionV3

Project-owned application or messaging surface declaration.

object
credential
Any of:
string
kind
required
Kind
string
Allowed values: app_backend linq_imessage telegram
settings
Settings
object
key
additional properties
any
credentialRequirements
Credentialrequirements
object
key
additional properties
CredentialRequirementV3

Logical reusable credential handle; the source never contains its value.

object
description
Any of:
string
<= 500 characters
kind
required
Kind
string
Allowed values: api_key bearer oauth
provider
required
Provider
string
>= 1 characters <= 100 characters
scopes
Scopes
Array<string>
<= 100 items
identity
ProjectIdentityV3

Secret-free contract for resolving a stable signed-in application user.

object
audience
Any of:
string
>= 1 characters <= 300 characters
issuer_url
Any of:
string
>= 1 characters <= 2000 characters
jwks_url
Any of:
string
>= 1 characters <= 2000 characters
mode
Mode
string
default: app_backend
Allowed values: app_backend oidc
tenant_id_claim
Any of:
string
>= 1 characters <= 120 characters
user_id_claim
User Id Claim
string
default: sub >= 1 characters <= 120 characters
kind
required
Kind
string
Allowed value: Project
memoryNamespaces
Memorynamespaces
object
key
additional properties
MemoryNamespaceV3

Project-owned memory namespace available for explicit Agent grants.

object
description
Any of:
string
<= 500 characters
scope
Scope
string
default: user
Allowed values: user tenant project
sensitive_data
Sensitive Data
string
default: deny
Allowed values: deny allow_explicit
metadata
required
ProjectMetadataV3

Stable Project source identity and presentation labels.

object
display_name
Any of:
string
>= 1 characters <= 200 characters
name
required
Name
string
>= 1 characters <= 80 characters /^[a-z][a-z0-9-]*$/
version
Version
string
default: 1.0.0 >= 1 characters <= 40 characters
policy
ProjectPolicyV3

Project ceiling that an Agent may narrow but never widen.

object
allow_agent_skill_drafts
Allow Agent Skill Drafts
boolean
default: true
allowed_capability_risks
Allowed Capability Risks
Array<string>
Allowed values: read write destructive
history_persistence_allowed
History Persistence Allowed
boolean
default: true
max_concurrent_turns
Max Concurrent Turns
integer
default: 32 >= 1 <= 10000
max_tool_calls_per_turn
Max Tool Calls Per Turn
integer
default: 10 >= 1 <= 100
max_turn_seconds
Max Turn Seconds
integer
default: 120 >= 1 <= 900
messages_per_user_per_minute
Messages Per User Per Minute
integer
default: 30 >= 1 <= 10000
require_approval_for_write
Require Approval For Write
boolean
default: true
strict_pii_filtering
Strict Pii Filtering
boolean
trace_content_capture
Trace Content Capture
string
default: full
Allowed values: full metadata
trace_content_retention_days
Trace Content Retention Days
integer
default: 30 >= 1 <= 90
skills
Skills
object
key
additional properties
SkillV3

Project-owned Hermes Skill directory declaration.

object
asset
required
Asset
string
>= 1 characters <= 240 characters
description
Any of:
string
<= 500 characters
supporting_assets
Supporting Assets
Array<string>
<= 100 items
manifest
required
Manifest
string
project_id
required
Project Id
string format: uuid
revision
required
ProjectRevisionReferenceV3

Exact server-versioned desired-state head identity.

object
generation
required
Generation
integer
>= 1
revision_id
required
Revision Id
string format: uuid
source_fingerprint
required
Source Fingerprint
string
/^[0-9a-f]{64}$/
workspace_id
required
Workspace Id
string format: uuid
Example
{
  "api_version": "genaug.desired-state/v3",
  "assets": [
    {
      "content_type": "text/plain; charset=utf-8",
      "kind": "soul"
    }
  ],
  "document": {
    "agents": [
      {
        "delegations": [
          {
            "mode": "as_tool"
          }
        ],
        "entry": false,
        "memory": {
          "additionalProperty": "read"
        }
      }
    ],
    "apiVersion": "genaug/v3",
    "capabilities": {
      "additionalProperty": {
        "kind": "builtin",
        "method": "GET",
        "risk": "read",
        "transport": "streamable_http"
      }
    },
    "connections": {
      "additionalProperty": {
        "kind": "app_backend"
      }
    },
    "credentialRequirements": {
      "additionalProperty": {
        "kind": "api_key"
      }
    },
    "identity": {
      "mode": "app_backend",
      "user_id_claim": "sub"
    },
    "kind": "Project",
    "memoryNamespaces": {
      "additionalProperty": {
        "scope": "user",
        "sensitive_data": "deny"
      }
    },
    "metadata": {
      "version": "1.0.0"
    },
    "policy": {
      "allow_agent_skill_drafts": true,
      "allowed_capability_risks": [
        "read"
      ],
      "history_persistence_allowed": true,
      "max_concurrent_turns": 32,
      "max_tool_calls_per_turn": 10,
      "max_turn_seconds": 120,
      "messages_per_user_per_minute": 30,
      "require_approval_for_write": true,
      "strict_pii_filtering": false,
      "trace_content_capture": "full",
      "trace_content_retention_days": 30
    }
  }
}

401

Section titled “401”

Authentication failed with a resumable next action.

Media typeapplication/json
ManagementErrorEnvelope

FastAPI error envelope shared by v3 management endpoints.

object
detail
required
ManagementErrorResponse

One bounded error with a coding-agent-safe recovery action.

object
affected_resource
Any of:
string
message
required
Message
string
next_action
Any of:
string
operation_id
Any of:
string format: uuid
phase
Any of:
string
reason_code
required
Reason Code
string
Examplegenerated
{
  "detail": {
    "affected_resource": "example",
    "message": "example",
    "next_action": "example",
    "operation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "phase": "example",
    "reason_code": "example"
  }
}

403

Section titled “403”

The authenticated actor lacks the required Project authority.

Media typeapplication/json
ManagementErrorEnvelope

FastAPI error envelope shared by v3 management endpoints.

object
detail
required
ManagementErrorResponse

One bounded error with a coding-agent-safe recovery action.

object
affected_resource
Any of:
string
message
required
Message
string
next_action
Any of:
string
operation_id
Any of:
string format: uuid
phase
Any of:
string
reason_code
required
Reason Code
string
Examplegenerated
{
  "detail": {
    "affected_resource": "example",
    "message": "example",
    "next_action": "example",
    "operation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "phase": "example",
    "reason_code": "example"
  }
}

404

Section titled “404”

The scoped management resource was not found.

Media typeapplication/json
ManagementErrorEnvelope

FastAPI error envelope shared by v3 management endpoints.

object
detail
required
ManagementErrorResponse

One bounded error with a coding-agent-safe recovery action.

object
affected_resource
Any of:
string
message
required
Message
string
next_action
Any of:
string
operation_id
Any of:
string format: uuid
phase
Any of:
string
reason_code
required
Reason Code
string
Examplegenerated
{
  "detail": {
    "affected_resource": "example",
    "message": "example",
    "next_action": "example",
    "operation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "phase": "example",
    "reason_code": "example"
  }
}

409

Section titled “409”

A stable management invariant prevented progress.

Media typeapplication/json
ManagementErrorEnvelope

FastAPI error envelope shared by v3 management endpoints.

object
detail
required
ManagementErrorResponse

One bounded error with a coding-agent-safe recovery action.

object
affected_resource
Any of:
string
message
required
Message
string
next_action
Any of:
string
operation_id
Any of:
string format: uuid
phase
Any of:
string
reason_code
required
Reason Code
string
Examplegenerated
{
  "detail": {
    "affected_resource": "example",
    "message": "example",
    "next_action": "example",
    "operation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "phase": "example",
    "reason_code": "example"
  }
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}