Validate and host an agent-authored Grounded result

POST

/v1/grounded-artifacts

curl --request POST \
  --url https://www.cemented.ai/v1/grounded-artifacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "artifact": { "kind": "grounded_research_draft", "title": "example", "question": "example", "queries": [], "sources": [ { "id": "example", "title": "example", "content": "example", "publishedDate": "example", "author": "example", "quality": 1, "explanation": "example", "type": "web", "url": "https://example.com", "contentSha256": "example" } ], "evidence": [ { "id": "example", "sourceId": "example", "quote": "example" } ], "constants": [], "computed": [], "output": { "type": "markdown", "value": "example" } }, "publish": false, "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "research_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Validates exact evidence, citation placeholders, JSON Schema structured results, and agent-produced computed traces, then atomically materializes a completed Grounded request. When research_id is supplied, the same transaction delivers the answer to that live session and ends its stream. No hosted research provider is invoked and no research credits are charged. Results are private unless publish is true.

Authorizations

• BearerAuth
• ApiKeyHeader

Parameters

Header Parameters

Idempotency-Key

required

Retry key scoped to the authenticated user. Reusing it with the same body returns the original report; a different body returns 409.

string

>= 1 characters <= 200 characters

Retry key scoped to the authenticated user. Reusing it with the same body returns the original report; a different body returns 409.

Request Body ^required

Media type application/json

object

artifact

required

object

kind

required

string

Allowed values: grounded_research_draft

title

required

string

>= 1 characters <= 300 characters

question

required

string

>= 1 characters <= 20000 characters

queries

Array<object>

default: <= 400 items

object

query

required

string

>= 1 characters <= 1000 characters

desiredSnippets

required

string

>= 1 characters <= 2000 characters

sourceIds

Array<string>

default: <= 100 items

sources

required

Array

>= 1 items <= 100 items

One of:

object

object

id

required

string

/^[a-z][a-z0-9-]{0,63}$/

title

required

string

>= 1 characters <= 500 characters

content

required

string

>= 1 characters <= 4000000 characters

publishedDate

string | null

<= 100 characters

author

string | null

<= 1000 characters

quality

integer | null

<= 10

explanation

string | null

>= 1 characters <= 2000 characters

type

required

string

Allowed values: web

url

required

string format: uri

<= 4000 characters

contentSha256

string

/^[0-9a-f]{64}$/

object

object

id

required

string

/^[a-z][a-z0-9-]{0,63}$/

title

required

string

>= 1 characters <= 500 characters

content

required

string

>= 1 characters <= 4000000 characters

publishedDate

string | null

<= 100 characters

author

string | null

<= 1000 characters

quality

integer | null

<= 10

explanation

string | null

>= 1 characters <= 2000 characters

type

required

string

Allowed values: file

filename

required

string

>= 1 characters <= 500 characters

contentType

string

default: text/plain >= 1 characters <= 200 characters

evidence

required

Array<object>

>= 1 items <= 2000 items

object

id

required

string

/^[a-z][a-z0-9-]{0,63}$/

sourceId

required

string

/^[a-z][a-z0-9-]{0,63}$/

quote

required

string

>= 1 characters <= 200000 characters

constants

Array<object>

default: <= 2000 items

object

id

required

string

/^[a-z][a-z0-9-]{0,63}$/

label

required

string

>= 1 characters <= 200 characters

value

required

string

>= 1 characters <= 10000 characters /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:e[+-]?\d+)?$/

unit

string

>= 1 characters <= 30 characters

note

string

>= 1 characters <= 1000 characters

computed

Array<object>

default: <= 2000 items

object

id

required

string

/^[a-z][a-z0-9-]{0,63}$/

label

required

string

>= 1 characters <= 200 characters

code

required

string

>= 1 characters <= 500000 characters

formula

string

>= 1 characters <= 10000 characters

inputs

required

Array<object>

<= 2000 items

object

name

required

string

/^[A-Za-z_][A-Za-z0-9_]{0,63}$/

value

required

string

>= 1 characters <= 10000 characters /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:e[+-]?\d+)?$/

snippetId

string

/^[a-z][a-z0-9-]{0,63}$/

output

required

object

value

required

string

>= 1 characters <= 10000 characters

unit

string

>= 1 characters <= 30 characters

numeric

boolean

output

required

One of:

object

object

type

required

string

Allowed values: markdown

value

required

string

>= 1 characters <= 500000 characters

object

object

type

required

string

Allowed values: json_schema

name

required

string

>= 1 characters <= 64 characters /^[A-Za-z0-9_-]+$/

description

string

<= 2000 characters

schema

required

object

key

additional properties

strict

boolean | null

value

required

numericGrounding

Array<object>

default: <= 500 items

object

path

required

string

<= 4000 characters

computedId

required

string

/^[a-z][a-z0-9-]{0,63}$/

publish

boolean

project_id

string format: uuid

research_id

Live research session created by /v1/research-sessions. Completing the upload also delivers the report to that session and closes its stream.

string format: uuid

Responses

200

Idempotent replay of an existing successful upload

Media type application/json

object

id

required

string format: uuid

object

required

string

Allowed values: grounded_report

url

required

string format: uri

output

required

One of:

object

object

type

required

string

Allowed values: markdown

value

required

string

object

object

type

required

string

Allowed values: json_schema

schema

object

key

additional properties

value

required

published

required

boolean

project_id

required

string | null format: uuid

idempotent_replay

required

boolean

warnings

Array<object>

object

code

required

string

Allowed values: retrieval_unverified possible_unit_suffix unreferenced_passage ungrounded_number

path

required

string

message

required

string

suggestion

required

string

Example

{
  "object": "grounded_report",
  "output": {
    "type": "markdown"
  },
  "warnings": [
    {
      "code": "retrieval_unverified"
    }
  ]
}

201

Artifact validated and a completed report was created

Media type application/json

object

id

required

string format: uuid

object

required

string

Allowed values: grounded_report

url

required

string format: uri

output

required

One of:

object

object

type

required

string

Allowed values: markdown

value

required

string

object

object

type

required

string

Allowed values: json_schema

schema

object

key

additional properties

value

required

published

required

boolean

project_id

required

string | null format: uuid

idempotent_replay

required

boolean

warnings

Array<object>

object

code

required

string

Allowed values: retrieval_unverified possible_unit_suffix unreferenced_passage ungrounded_number

path

required

string

message

required

string

suggestion

required

string

Example

{
  "object": "grounded_report",
  "output": {
    "type": "markdown"
  },
  "warnings": [
    {
      "code": "retrieval_unverified"
    }
  ]
}

400

Malformed envelope, missing idempotency key, or a zero-data-retention account

Media type application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example ^generated

{
  "error": {
    "message": "example",
    "type": "example",
    "code": "example"
  }
}

401

Unauthorized

Media type application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example ^generated

{
  "error": {
    "message": "example",
    "type": "example",
    "code": "example"
  }
}

404

The requested project or research session does not exist or is inaccessible

Media type application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example ^generated

{
  "error": {
    "message": "example",
    "type": "example",
    "code": "example"
  }
}

409

The idempotency key was already used with a different upload body, or the research session already has a different report

Media type application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example ^generated

{
  "error": {
    "message": "example",
    "type": "example",
    "code": "example"
  }
}

422

The artifact is well-formed JSON but fails one or more Grounded invariants

Media type application/json

object

error

required

object

message

required

string

type

required

string

Allowed values: invalid_request_error

code

required

string

Allowed values: artifact_validation_failed

issues

required

Array<object>

object

code

required

string

Allowed values: invalid_draft duplicate_id unknown_source evidence_not_found unknown_token unknown_citation unverified_quote invalid_computed invalid_link invalid_output_schema invalid_structured_output invalid_grounding_path compiled_report_too_large invalid_artifact unresolved_content_hash unknown_content_hash content_hash_mismatch missing_grounding

path

required

string

message

required

string

suggestion

required

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "artifact_validation_failed",
    "issues": [
      {
        "code": "invalid_draft"
      }
    ]
  }
}