Skip to content
Cemented AI

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" }'

Validates exact evidence, citation placeholders, JSON Schema structured results, and agent-produced computed traces, then atomically materializes a completed Grounded request. No hosted research provider is invoked and no research credits are charged. Results are private unless publish is true.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “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

Section titled “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
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}$/
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
type
required
string
Allowed values: markdown
value
required
string
>= 1 characters <= 500000 characters
publish
boolean
project_id
string format: uuid

Responses

Section titled “ Responses ”

200

Section titled “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
type
required
string
Allowed values: markdown
value
required
string
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

Section titled “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
type
required
string
Allowed values: markdown
value
required
string
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

Section titled “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

Section titled “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

Section titled “404 ”

The requested project 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

Section titled “409 ”

The idempotency key was already used with a different upload body

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

Section titled “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"
      }
    ]
  }
}