Jev evaluations

Evaluate user-supplied questions (cannot approve voice settings)

Use this endpoint from your own integration, with the same account permissions and safeguards as the app.

Scope · jev:writeIdempotency-Key required10 expensive operations / minute / user

Request

POST/api/v1/jev/evaluate

Example requestcURL

curl -X POST 'https://postlift.io/api/v1/jev/evaluate' \
  -H "Authorization: Bearer $POSTLIFT_API_KEY" \
  -H 'Idempotency-Key: integration-operation-0001' \
  -H 'Content-Type: application/json' \
  --data '{
  "state": {
    "text": "A small release beats a perfect plan."
  },
  "questions": {
    "clear": {
      "type": "boolean",
      "instructions": "Does this post communicate a clear idea?"
    }
  }
}'

Replace path placeholders with your Postlift resource IDs. Example timestamps must be replaced with a future time; preserve the same timestamp when retrying the same operation.

Parameters

Name	Location	Description
`Idempotency-Key`required	header	Unique operation key. Reuse only for the same payload/account. See retry semantics in the guide.Pattern: ^[A-Za-z0-9_-]{8,128}$.

Request body

Send JSON with Content-Type: application/json.

Field	Type & constraints
`state`required	string \| object \| post_jev_evaluate_Request ↗ []
`questions`required	object

View JSON schema

{
  "type": "object",
  "properties": {
    "state": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/components/schemas/post_jev_evaluate_Request/$defs/__schema0"
          }
        },
        {
          "minItems": 1,
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/post_jev_evaluate_Request/$defs/__schema1"
          }
        }
      ]
    },
    "questions": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$"
      },
      "additionalProperties": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "boolean"
              },
              "instructions": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1024
              },
              "criteria": {
                "type": "object",
                "properties": {
                  "true": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 512
                  },
                  "false": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 512
                  }
                },
                "required": [
                  "true",
                  "false"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "type",
              "instructions"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "choice"
              },
              "instructions": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1024
              },
              "criteria": {
                "type": "object",
                "propertyNames": {
                  "type": "string",
                  "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$"
                },
                "additionalProperties": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 512
                }
              }
            },
            "required": [
              "type",
              "instructions",
              "criteria"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "score"
              },
              "instructions": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1024
              },
              "criteria": {
                "minItems": 2,
                "maxItems": 10,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 512
                }
              }
            },
            "required": [
              "type",
              "instructions",
              "criteria"
            ],
            "additionalProperties": false
          }
        ]
      }
    }
  },
  "required": [
    "state",
    "questions"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/post_jev_evaluate_Request/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/components/schemas/post_jev_evaluate_Request/$defs/__schema0"
          }
        }
      ]
    },
    "__schema1": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/post_jev_evaluate_Request/$defs/__schema1"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/components/schemas/post_jev_evaluate_Request/$defs/__schema1"
          }
        }
      ]
    }
  }
}

Response

200 Successful operation.

Field	Type & constraints
`requestId`required	string
`model`required	string
`resolvedModel`required	string
`answers`required	object
`usage`required	object

Explore JevEvaluation ↗

View JSON schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "model": {
      "type": "string"
    },
    "resolvedModel": {
      "type": "string"
    },
    "answers": {
      "type": "object",
      "additionalProperties": true
    },
    "usage": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "required": [
    "requestId",
    "model",
    "resolvedModel",
    "answers",
    "usage"
  ],
  "additionalProperties": true
}

Errors & retries

Failures use a stable error code and request ID. Check the current resource version or request status before retrying a write.

Status	Meaning
`400`	Invalid input or Jev rejection
`401`	Invalid, expired or revoked API key
`402`	Plan, publishing quota or AI credit requirement
`403`	Missing scope
`404`	Resource not found or not owned
`409`	Version conflict, missing voice or duplicate AI operation
`413`	Payload too large
`429`	Rate or concurrency limit
`500`	Internal error
`502`	Upstream failure; inspect operation status
`503`	Service or review unavailable

Read the retry guide ↗