EQTY LabDocs

Get a state-referenced project agent blob

Returns a child blob only when the authorized state attestation directly references its CID and the scoped agent has uploader provenance for the blob. With alt=media, a 200 response is the blob's raw bytes (application/octet-stream, exact Content-Length, Content-Disposition: attachment) instead of the JSON envelope; errors stay JSON. The JSON envelope refuses a blob over 16 MiB with 422 referenced_blob_too_large; read it with alt=media, which has no limit of its own. max_bytes refuses a larger blob the same way, before it is loaded.

gethttps://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}/state-cids/{state_cid}/blobs/{cid}
bash
curl --request GET \
  --url 'https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}/state-cids/{state_cid}/blobs/{cid}' \
  --header 'Authorization: Bearer <token>'
javascript
const response = await fetch("https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}/state-cids/{state_cid}/blobs/{cid}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <token>"
  }
});

const data = await response.json();
typescript
interface ProjectBlobResponse {
  agent_id?: string;
  blob?: string;
  bootstrap_decision_code?: string;
  bootstrap_outcome?: string;
  cid?: string;
  correlation_id?: string;
  data_scope?: Record<string, unknown>;
  encoding?: string;
  membership_credential_id?: string;
  membership_established?: boolean;
  membership_issuer_did?: string;
  membership_validation_status?: string;
  plugin_configuration_global_id?: string;
  plugin_configuration_global_version?: number;
  plugin_configuration_project_id?: string;
  plugin_configuration_project_version?: number;
  project_candidate_urn?: string;
  project_context_mode?: string;
  project_reason_code?: string;
  project_resolution_source?: string;
  project_urn?: string;
  resolved_iroh_collections_blob?: string;
  resolved_iroh_collections_encoding?: string;
  size_bytes?: number;
  state_cid?: string;
  state_correlation_id?: string;
}

const response = await fetch("https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}/state-cids/{state_cid}/blobs/{cid}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <token>"
  }
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);

const data: ProjectBlobResponse = await response.json();
python
import requests

response = requests.get(
    "https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}/state-cids/{state_cid}/blobs/{cid}",
    headers={
        "Authorization": "Bearer <token>",
    },
)
response.raise_for_status()
print(response.json())
go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}/state-cids/{state_cid}/blobs/{cid}", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(res.Status, string(data))
}
java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}/state-cids/{state_cid}/blobs/{cid}"))
            .header("Authorization", "Bearer <token>")
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
csharp
using System.Net.Http.Headers;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}/state-cids/{state_cid}/blobs/{cid}");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<token>");

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
php
<?php

$ch = curl_init('https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}/state-cids/{state_cid}/blobs/{cid}');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <token>',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $status . " " . $response . PHP_EOL;
ruby
require "net/http"

uri = URI("https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}/state-cids/{state_cid}/blobs/{cid}")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer <token>"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
puts "#{response.code} #{response.body}"
rust
// Cargo.toml dependencies: reqwest, tokio (features "full")

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let response = reqwest::Client::new()
        .get("https://<host>/api/v1/projects/{project_uuid}/agents/{agent_id}/state-cids/{state_cid}/blobs/{cid}")
        .header("Authorization", "Bearer <token>")
        .send()
        .await?;

    println!("{} {}", response.status(), response.text().await?);
    Ok(())
}

Authorizations

  • BearerAuth · API key in header "Authorization" — Type "Bearer" followed by a space and a sign-in token: a Guardian Platform JWT, or an OIDC ID token in a standalone deployment.
  • ApiKeyAuth · API key in header "Authorization" — Type "Bearer" followed by a space and a Guardian Platform API key. Project-scoped routes and registration tokens check the key's scopes and project binding. Per-agent routes accept a key bound to no project that has empty scopes or full access, which acts as its holder, or a scope for what the route does: submit_agent_assessments reads an agent (its detail, configurations, state history and the files a state references, definitions, tools and operating profile, as its assessments rest on), view_agent_certifications reads its certifications, and manage_programs or review_agent_assessments attach a certification. A state's raw snapshot and findings, its audit exchanges and plugin events, and saving its operating profile take full access. A scope counts only while the key's holder still holds that permission in the key's organization, which auth-service reports as keyHeldScopes. A key never acts as an admin, so its holder's binding to the agent still decides.

Parameters

Path parameters

NameTypeDescription
project_uuid
required
string

Guardian project UUID

agent_id
required
string

Gateway agent ID or membership subject DID

state_cid
required
string

Authorized parent state CID

cid
required
string

Directly referenced child CID

Query parameters

NameTypeDescription
altstring (enum)

media returns the raw bytes instead of the JSON envelope

One ofmedia

max_bytesinteger

Refuse a blob larger than this many bytes with 422 referenced_blob_too_large, before it is loaded; can only lower the route's limit

Responses

200OK

application/json
  • agent_idstring
  • blobstring
  • bootstrap_decision_codestring
  • bootstrap_outcomestring
  • cidstring
  • correlation_idstring
  • data_scopegithub_com_eqtylab_gateway_control-plane_service_internal_discovery.ProjectDataScope
    Show github_com_eqtylab_gateway_control-plane_service_internal_discovery.ProjectDataScope
    • authoritystring
    • legacy_records_excludedboolean
    • project_urnstring
    • scopestring
  • encodingstring
  • membership_credential_idstring
  • membership_establishedboolean
  • membership_issuer_didstring
  • membership_validation_statusstring
  • plugin_configuration_global_idstring
  • plugin_configuration_global_versioninteger
  • plugin_configuration_project_idstring
  • plugin_configuration_project_versioninteger
  • project_candidate_urnstring
  • project_context_modestring
  • project_reason_codestring
  • project_resolution_sourcestring
  • project_urnstring
  • resolved_iroh_collections_blobstring
  • resolved_iroh_collections_encodingstring
  • size_bytesinteger
  • state_cidstring
  • state_correlation_idstring
Examplejson
{
  "agent_id": "string",
  "blob": "string",
  "bootstrap_decision_code": "string",
  "bootstrap_outcome": "string",
  "cid": "string",
  "correlation_id": "string",
  "data_scope": {
    "authority": "string",
    "legacy_records_excluded": true,
    "project_urn": "string",
    "scope": "string"
  },
  "encoding": "string",
  "membership_credential_id": "string",
  "membership_established": true,
  "membership_issuer_did": "string",
  "membership_validation_status": "string",
  "plugin_configuration_global_id": "string",
  "plugin_configuration_global_version": 0,
  "plugin_configuration_project_id": "string",
  "plugin_configuration_project_version": 0,
  "project_candidate_urn": "string",
  "project_context_mode": "string",
  "project_reason_code": "string",
  "project_resolution_source": "string",
  "project_urn": "string",
  "resolved_iroh_collections_blob": "string",
  "resolved_iroh_collections_encoding": "string",
  "size_bytes": 0,
  "state_cid": "string",
  "state_correlation_id": "string"
}
application/octet-stream
  • agent_idstring
  • blobstring
  • bootstrap_decision_codestring
  • bootstrap_outcomestring
  • cidstring
  • correlation_idstring
  • data_scopegithub_com_eqtylab_gateway_control-plane_service_internal_discovery.ProjectDataScope
    Show github_com_eqtylab_gateway_control-plane_service_internal_discovery.ProjectDataScope
    • authoritystring
    • legacy_records_excludedboolean
    • project_urnstring
    • scopestring
  • encodingstring
  • membership_credential_idstring
  • membership_establishedboolean
  • membership_issuer_didstring
  • membership_validation_statusstring
  • plugin_configuration_global_idstring
  • plugin_configuration_global_versioninteger
  • plugin_configuration_project_idstring
  • plugin_configuration_project_versioninteger
  • project_candidate_urnstring
  • project_context_modestring
  • project_reason_codestring
  • project_resolution_sourcestring
  • project_urnstring
  • resolved_iroh_collections_blobstring
  • resolved_iroh_collections_encodingstring
  • size_bytesinteger
  • state_cidstring
  • state_correlation_idstring

400Bad Request

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}
application/octet-stream
  • codestring
  • correlation_idstring
  • messagestring

401Unauthorized

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}
application/octet-stream
  • codestring
  • correlation_idstring
  • messagestring

403Forbidden

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}
application/octet-stream
  • codestring
  • correlation_idstring
  • messagestring

404Not Found

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}
application/octet-stream
  • codestring
  • correlation_idstring
  • messagestring

422Unprocessable Entity

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}
application/octet-stream
  • codestring
  • correlation_idstring
  • messagestring

500Internal Server Error

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}
application/octet-stream
  • codestring
  • correlation_idstring
  • messagestring

503Service Unavailable

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}
application/octet-stream
  • codestring
  • correlation_idstring
  • messagestring