stable · api · 0.1.0

Submit one constrained Project Audit fact

POST /api/v1/project-audits

Capability Domain: Security Audit Privacy

Authentication

projectCredential (audit:write)

Scope: audit:write

Parameters and request body

Idempotency-Key — header, required
Idempotency-Key schema
```
{
    "type": "string",
    "maxLength": 255
}
```
X-Correlation-ID — header, optional
X-Correlation-ID schema
```
{
    "type": "string",
    "format": "uuid"
}
```

Request schema

application/json

application/json request schema

{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "actor_id",
        "action",
        "resource_type",
        "resource_id",
        "outcome"
    ],
    "properties": {
        "actor_id": {
            "type": "string",
            "maxLength": 180,
            "pattern": "^(?:[A-Za-z][A-Za-z0-9_]*:)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
        },
        "action": {
            "type": "string",
            "maxLength": 180,
            "pattern": "^[a-z][a-z0-9_.-]+$"
        },
        "resource_type": {
            "type": "string",
            "maxLength": 120,
            "pattern": "^[A-Z][A-Za-z0-9]+$"
        },
        "resource_id": {
            "type": "string",
            "maxLength": 180,
            "pattern": "^(?:[A-Za-z][A-Za-z0-9_]*:)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
        },
        "outcome": {
            "type": "string",
            "enum": [
                "succeeded",
                "failed",
                "denied"
            ]
        }
    }
}

application/json request example

{
    "actor_id": "actor:38000000-0000-4000-8000-000000000010",
    "action": "project.membership.changed",
    "resource_type": "ProjectMembership",
    "resource_id": "membership:38000000-0000-4000-8000-000000000011",
    "outcome": "succeeded"
}

Responses and errors

Status	Description
`201`	Project Audit fact accepted or identically replayed
`401`	Invalid or revoked Project Credential
`403`	Project Credential lacks the required scope
`422`	Request violates the public contract
`429`	Project Client hard quota reached

201 schema

201 response schema

{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "data"
    ],
    "properties": {
        "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "id"
            ],
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                }
            }
        }
    }
}

401 schema

401 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

403 schema

403 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

422 schema

422 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

429 schema

429 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "details",
                "correlation_id"
            ],
            "properties": {
                "code": {
                    "type": "string",
                    "enum": [
                        "platform_quota_exceeded"
                    ]
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean",
                    "enum": [
                        true
                    ]
                },
                "details": {
                    "type": "object",
                    "required": [
                        "resource",
                        "used",
                        "limit",
                        "retry_after_seconds"
                    ],
                    "properties": {
                        "resource": {
                            "type": "string",
                            "enum": [
                                "api_traffic",
                                "storage_bytes",
                                "deliveries",
                                "events",
                                "scheduled_invocations",
                                "realtime_connections",
                                "payment_transactions",
                                "audit_retention"
                            ]
                        },
                        "used": {
                            "type": "integer",
                            "minimum": 0
                        },
                        "limit": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "retry_after_seconds": {
                            "type": "integer",
                            "minimum": 1
                        }
                    }
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                }
            }
        }
    }
}

201 example

201 response example

{
    "data": {
        "id": "38000000-0000-4000-8000-000000000012"
    }
}

429 example

429 response example

{
    "error": {
        "code": "platform_quota_exceeded",
        "message": "The platform resource hard limit has been reached.",
        "retryable": true,
        "details": {
            "resource": "api_traffic",
            "used": 1000,
            "limit": 1000,
            "retry_after_seconds": 312
        },
        "correlation_id": "20000000-0000-4000-8000-000000000016"
    }
}

Idempotency

Requires Idempotency-Key. Repeating the identical fact returns the same Project Audit ID; reusing the key for different facts is rejected.