Agent Execution Contract Intelligence API Documentation

POSThttps://www.brainiac.software/api/v1/agent-contracts/expiry-contract-check$0.03 USDC

Check expiry contracts

Find presigned URLs and access tokens in caller-supplied operations that do not state a lifetime, and sentences that both expire and never expire. A missing lifetime is undocumented, not a live-server defect.

Body

Field	Required	Notes
`operations`	No	array; Array
`workflows`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "operations": [
    {
      "name": "create_upload",
      "description": "Returns a presigned upload URL.",
      "outputSchema": {
        "type": "object",
        "properties": {
          "upload_url": {
            "type": "string",
            "description": "URL the agent uploads to."
          },
          "download_url": {
            "type": "string",
            "description": "Download URL. Expires in 15 minutes."
          }
        }
      }
    },
    {
      "name": "issue_token",
      "description": "The access token never expires. It expires in 5 minutes.",
      "outputSchema": {
        "type": "object",
        "properties": {
          "access_token": {
            "type": "string",
            "description": "Bearer token."
          }
        }
      }
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Checked 2 operations that name a temporary URL or token.",
  "score": 55,
  "issues": [
    {
      "type": "missing_expiry",
      "severity": "high",
      "description": "A temporary URL or token is named, and neither the field nor the operation states when it stops being valid. The lifetime is undocumented, not observed.",
      "evidence": "upload_url",
      "location": "operations[0].outputSchema.properties.upload_url",
      "agent_impact": "An agent may call the URL after it has stopped working, or it may refresh a value that the contract never says to refresh.",
      "suggested_fix": "State the lifetime, such as expires in 15 minutes, or name an expires_at field."
    },
    {
      "type": "contradictory_expiry",
      "severity": "high",
      "description": "The same description both gives a lifetime and says the value does not expire. These are conflicting sentences in the contract.",
      "evidence": "The access token never expires. It expires in 5 minutes.",
      "location": "operations[1]",
      "agent_impact": "An agent cannot decide whether to refresh the URL or token before using it.",
      "suggested_fix": "Keep one statement: a lifetime, or an explicit statement that it does not expire."
    }
  ],
  "warnings": [],
  "recommendations": [],
  "limitations": [
    "Checks read only the supplied operations, workflows, and OpenAPI document. No URL is fetched and no model reads the text.",
    "A missing sentence is an undocumented contract. It is not a confirmed defect in a running implementation.",
    "A contradiction is two statements in the supplied text. It is not proof of how a server behaves.",
    "The HTTP method is not evidence that an operation is safe to retry or that it is idempotent.",
    "Matches are fixed phrases and field names. They do not infer a business rule that the text does not state.",
    "Temporary names are presigned or signed URLs, upload and download URLs, access, refresh, and session tokens, and one-time codes. A bare url or token is not enough.",
    "A sibling expires, expiry, or ttl field counts as documented lifetime. Each missing lifetime subtracts 20. A contradiction subtracts 25.",
    "The score is omitted when the document names no temporary resource."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-contracts/expiry-contract-check" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "operations": [
    {
      "name": "create_upload",
      "description": "Returns a presigned upload URL.",
      "outputSchema": {
        "type": "object",
        "properties": {
          "upload_url": {
            "type": "string",
            "description": "URL the agent uploads to."
          },
          "download_url": {
            "type": "string",
            "description": "Download URL. Expires in 15 minutes."
          }
        }
      }
    },
    {
      "name": "issue_token",
      "description": "The access token never expires. It expires in 5 minutes.",
      "outputSchema": {
        "type": "object",
        "properties": {
          "access_token": {
            "type": "string",
            "description": "Bearer token."
          }
        }
      }
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-contracts/retry-safety-check$0.03 USDC

Check retry safety contracts

Read caller-supplied retry sentences and timeout statuses. A timeout with no retry sentence is missing documentation. The HTTP method is not treated as safe or unsafe to retry.

Body

Field	Required	Notes
`operations`	No	array; Array
`workflows`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "operations": [
    {
      "name": "charge_card",
      "method": "POST",
      "description": "Charges the saved card. A timeout means the outcome is uncertain.",
      "responses": [
        {
          "status": "504",
          "description": "Gateway timeout."
        }
      ]
    },
    {
      "name": "reserve_stock",
      "method": "POST",
      "description": "Reserves stock. Safe to retry. Do not retry after a timeout."
    },
    {
      "name": "read_order",
      "method": "GET",
      "description": "Returns one order by id."
    }
  ]
}

Response exampleJSON

{
"success": true,
"analysis": "Checked retry sentences on 3 operations. A method name was not read as safe or unsafe.",
"score": 55,
"issues": [
{
"type": "missing_retry_policy",
"severity": "high",
"description": "The contract describes a timeout or an uncertain outcome and does not say whether to retry. The HTTP method was not treated as a retry rule.",
"evidence": "Charges the saved card. A timeout means the outcome is uncertain. Gateway timeout.",
"location": "operations[0]",
"agent_impact": "After a timeout an agent may charge or create a second time, or it may stop even though the first call succeeded.",
"suggested_fix": "State whether that timeout is safe to retry, or tell the agent to read a status operation instead."
},
{
"type": "contradictory_retry",
"severity": "high",
"description": "The contract both says a retry is safe and says not to retry. The HTTP method was not used.",
"evidence": "Reserves stock. Safe to retry. Do not retry after a timeout.",
"location": "operations[1]",
"agent_impact": "An agent can repeat a call the contract also forbids, or abandon a call the contract says to repeat.",
"suggested_fix": "Keep one retry rule and name the status or timeout it applies to."
}
],
"warnings": [
{
"type": "retry_not_documented",
"severity": "medium",
"description": "The contract does not say whether a retry is safe. Silence is not a retry policy, and the HTTP method is not one either.",
"evidence": "GET",
"location": "operations[2]",
"agent_impact": "An agent has no contract rule for a dropped response and may invent one from the method.",
"suggested_fix": "Add a sentence such as safe to retry or do not retry, and the outcome it applies to."
}
],
"recommendations": [],
"limitations": [
"Checks read only the supplied operations, workflows, and OpenAPI document. No URL is fetched and no model reads the text.",
"A missing sentence is an undocumented contract. It is not a confirmed defect in a running implementation.",
"A contradiction is two statements in the supplied text. It is not proof of how a server behaves.",
"The HTTP method is not evidence that an operation is safe to retry or that it is idempotent.",
"Matches are fixed phrases and field names. They do not infer a business rule that the text does not state.",
"Safe phrases include safe to retry, may be retried, and retries are safe. Unsafe phrases include do not retry and not safe to retry.",
"Uncertain outcomes are the words timeout, uncertain, unknown outcome, may have succeeded, and in-flight, plus response statuses 408 and 504.",
"A contradiction subtracts 25. A timeout with no retry sentence subtracts 20. Silence without a timeout is a warning and does not change the score."
]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-contracts/retry-safety-check" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "operations": [
    {
      "name": "charge_card",
      "method": "POST",
      "description": "Charges the saved card. A timeout means the outcome is uncertain.",
      "responses": [
        {
          "status": "504",
          "description": "Gateway timeout."
        }
      ]
    },
    {
      "name": "reserve_stock",
      "method": "POST",
      "description": "Reserves stock. Safe to retry. Do not retry after a timeout."
    },
    {
      "name": "read_order",
      "method": "GET",
      "description": "Returns one order by id."
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-contracts/idempotency-audit$0.04 USDC

Audit idempotency contracts

Find create or update sentences that do not name an idempotency key or a replay result. The check does not call an operation idempotent unless the supplied text says so, and POST alone is not proof of a write.

Body

Field	Required	Notes
`operations`	No	array; Array
`workflows`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "operations": [
    {
      "name": "create_order",
      "method": "POST",
      "description": "Creates an order for the sku."
    },
    {
      "name": "create_payment",
      "method": "POST",
      "description": "Creates a payment. An Idempotency-Key returns the same payment on replay. Every call creates a new payment."
    },
    {
      "name": "search_orders",
      "method": "GET",
      "description": "Returns orders that match the email."
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Checked 3 operations for a stated create or update and a stated replay rule. No operation was marked idempotent unless the text says so.",
  "score": 55,
  "issues": [
    {
      "type": "missing_idempotency",
      "severity": "high",
      "description": "The text says the operation creates or changes something, and it does not name an idempotency key or a replay result. This is missing documentation, not proof of a duplicate write.",
      "evidence": "Creates an order for the sku.",
      "location": "operations[0]",
      "agent_impact": "An agent that retries can create a second charge, order, or message because the contract never says what a repeat does.",
      "suggested_fix": "Name an Idempotency-Key and say whether a replay returns the original result."
    },
    {
      "type": "contradictory_idempotency",
      "severity": "high",
      "description": "The contract says a replay returns the same result and also says each call creates a new one. Both sentences are in the supplied text.",
      "evidence": "Creates a payment. An Idempotency-Key returns the same payment on replay. Every call creates a new payment.",
      "location": "operations[1]",
      "agent_impact": "An agent cannot tell whether to reuse an idempotency key or to expect a second resource.",
      "suggested_fix": "Delete one of the two sentences so the replay result is unambiguous."
    }
  ],
  "warnings": [],
  "recommendations": [],
  "limitations": [
    "Checks read only the supplied operations, workflows, and OpenAPI document. No URL is fetched and no model reads the text.",
    "A missing sentence is an undocumented contract. It is not a confirmed defect in a running implementation.",
    "A contradiction is two statements in the supplied text. It is not proof of how a server behaves.",
    "The HTTP method is not evidence that an operation is safe to retry or that it is idempotent.",
    "Matches are fixed phrases and field names. They do not infer a business rule that the text does not state.",
    "A state change is a fixed verb such as create, update, delete, charge, send, submit, transfer, cancel, write, insert, or remove.",
    "Idempotency text is the word idempotent, Idempotency-Key, replay, or same result. A key name without that sentence stays a warning.",
    "Missing idempotency subtracts 20. A contradiction subtracts 25. Warnings do not change the score."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-contracts/idempotency-audit" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "operations": [
    {
      "name": "create_order",
      "method": "POST",
      "description": "Creates an order for the sku."
    },
    {
      "name": "create_payment",
      "method": "POST",
      "description": "Creates a payment. An Idempotency-Key returns the same payment on replay. Every call creates a new payment."
    },
    {
      "name": "search_orders",
      "method": "GET",
      "description": "Returns orders that match the email."
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-contracts/pagination-contract-check$0.03 USDC

Check pagination contracts

Find page or cursor operations in caller-supplied OpenAPI or tool definitions that omit the next-page field, the end condition, or which of cursor and offset to follow.

Body

Field	Required	Notes
`operations`	No	array; Array
`workflows`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "openapi": {
    "openapi": "3.1.0",
    "paths": {
      "/orders": {
        "get": {
          "operationId": "list_orders",
          "description": "Returns a page of orders.",
          "parameters": [
            {
              "name": "cursor",
              "in": "query",
              "description": "Page cursor.",
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "offset",
              "in": "query",
              "description": "Record offset.",
              "schema": {
                "type": "integer"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "Orders",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "orders": {
                        "type": "array"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Response exampleJSON

{
  "success": true,
  "analysis": "Checked 1 operations that mention a page, cursor, or offset.",
  "score": 48,
  "issues": [
    {
      "type": "missing_continuation",
      "severity": "high",
      "description": "The contract describes a page or a cursor and does not name the response field that leads to the next page.",
      "evidence": "cursor",
      "location": "openapi.paths[/orders].get",
      "agent_impact": "An agent can stop after the first page or loop because it has no declared continuation field.",
      "suggested_fix": "Name the response field, such as next_cursor, and the request field that receives it."
    },
    {
      "type": "unclear_cursor",
      "severity": "medium",
      "description": "A cursor parameter is named, and the text does not say whether it is opaque, how the first page is requested, or when it expires.",
      "evidence": "Page cursor.",
      "location": "openapi.paths[/orders].get.parameters.cursor",
      "agent_impact": "An agent may parse the cursor, omit it incorrectly, or reuse it after it stops working.",
      "suggested_fix": "Say to omit it for the first page, whether it is opaque, and whether it expires."
    },
    {
      "type": "unclear_termination",
      "severity": "high",
      "description": "The contract does not say how the agent knows the last page has been reached.",
      "evidence": "list_orders",
      "location": "openapi.paths[/orders].get",
      "agent_impact": "An agent can keep requesting pages after the list has ended.",
      "suggested_fix": "State the end condition, such as a null next cursor, has_more false, or an empty page."
    },
    {
      "type": "conflicting_pagination",
      "severity": "medium",
      "description": "Both a cursor and an offset or page parameter are declared, and the text does not say which one to follow.",
      "evidence": "cursor, offset",
      "location": "openapi.paths[/orders].get",
      "agent_impact": "An agent can send both and skip or repeat records.",
      "suggested_fix": "Tell the agent to use one continuation style and ignore the other."
    }
  ],
  "warnings": [],
  "recommendations": [],
  "limitations": [
    "Checks read only the supplied operations, workflows, and OpenAPI document. No URL is fetched and no model reads the text.",
    "A missing sentence is an undocumented contract. It is not a confirmed defect in a running implementation.",
    "A contradiction is two statements in the supplied text. It is not proof of how a server behaves.",
    "The HTTP method is not evidence that an operation is safe to retry or that it is idempotent.",
    "Matches are fixed phrases and field names. They do not infer a business rule that the text does not state.",
    "A continuation field is next, next_cursor, next_page, continuation_token, or next_page_token. A bare limit is not a continuation.",
    "Termination is has_more, total, or a sentence such as null next cursor or last page.",
    "Missing continuation or termination subtracts 15. An unclear cursor subtracts 10. Cursor plus offset subtracts 12. The score is omitted when nothing describes a page."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-contracts/pagination-contract-check" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "openapi": {
    "openapi": "3.1.0",
    "paths": {
      "/orders": {
        "get": {
          "operationId": "list_orders",
          "description": "Returns a page of orders.",
          "parameters": [
            {
              "name": "cursor",
              "in": "query",
              "description": "Page cursor.",
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "offset",
              "in": "query",
              "description": "Record offset.",
              "schema": {
                "type": "integer"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "Orders",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "orders": {
                        "type": "array"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-contracts/error-recovery-audit$0.04 USDC

Audit error recovery contracts

Check whether caller-supplied 4xx and 5xx responses name a code, message, or field an agent can correct. A missing error schema is undocumented, not proof the server never fails.

Body

Field	Required	Notes
`operations`	No	array; Array
`workflows`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "operations": [
    {
      "name": "create_order",
      "description": "Creates an order.",
      "parameters": [
        {
          "name": "sku",
          "in": "body",
          "description": "Stock keeping unit."
        }
      ],
      "responses": [
        {
          "status": "400",
          "description": "Bad request."
        },
        {
          "status": "201",
          "description": "Created."
        }
      ]
    },
    {
      "name": "capture_payment",
      "description": "Captures an authorized payment.",
      "responses": [
        {
          "status": "200",
          "description": "Captured."
        }
      ]
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Checked error responses on 2 operations.",
  "score": 65,
  "issues": [
    {
      "type": "opaque_error",
      "severity": "high",
      "description": "The error text is a generic label and the schema has no code, message, or field. The agent is not told how to correct the request.",
      "evidence": "Bad request.",
      "location": "operations[0].responses[0]",
      "agent_impact": "An agent cannot tell which parameter to change, so it may repeat the same request.",
      "suggested_fix": "Name the rejected field and add a code or message property."
    },
    {
      "type": "no_error_contract",
      "severity": "high",
      "description": "No 4xx or 5xx response is documented. The failure shape is missing from the contract, which does not prove the server never fails.",
      "evidence": "capture_payment",
      "location": "operations[1]",
      "agent_impact": "An agent that receives an error has no documented way to correct the next call.",
      "suggested_fix": "Document the error statuses and a machine-readable code or field."
    }
  ],
  "warnings": [],
  "recommendations": [],
  "limitations": [
    "Checks read only the supplied operations, workflows, and OpenAPI document. No URL is fetched and no model reads the text.",
    "A missing sentence is an undocumented contract. It is not a confirmed defect in a running implementation.",
    "A contradiction is two statements in the supplied text. It is not proof of how a server behaves.",
    "The HTTP method is not evidence that an operation is safe to retry or that it is idempotent.",
    "Matches are fixed phrases and field names. They do not infer a business rule that the text does not state.",
    "A useful error schema has one of code, message, error, errors, field, details, type, title, parameter, path, or reason.",
    "A description that names a supplied parameter, or the word field or parameter, counts as a correction target.",
    "A missing error contract subtracts 20. A generic error subtracts 15. An error with no correction target subtracts 10."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-contracts/error-recovery-audit" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "operations": [
    {
      "name": "create_order",
      "description": "Creates an order.",
      "parameters": [
        {
          "name": "sku",
          "in": "body",
          "description": "Stock keeping unit."
        }
      ],
      "responses": [
        {
          "status": "400",
          "description": "Bad request."
        },
        {
          "status": "201",
          "description": "Created."
        }
      ]
    },
    {
      "name": "capture_payment",
      "description": "Captures an authorized payment.",
      "responses": [
        {
          "status": "200",
          "description": "Captured."
        }
      ]
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-contracts/output-contract-check$0.04 USDC

Check output contracts

Compare caller-supplied success examples with their output schemas for type, enum, required fields, and extra properties. A mismatch is a conflict between those documents, not a confirmed live response.

Body

Field	Required	Notes
`operations`	No	array; Array
`workflows`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "operations": [
    {
      "name": "create_order",
      "outputSchema": {
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "submitted"
            ]
          }
        }
      },
      "examples": [
        {
          "id": 15,
          "status": "shipped",
          "note": "rush"
        },
        {
          "id": "ord_1",
          "status": "draft"
        }
      ]
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Compared 2 success examples with their output schemas. 1 matched.",
  "score": 50,
  "issues": [
    {
      "type": "example_schema_mismatch",
      "severity": "medium",
      "description": "The supplied example includes a field the schema says is not part of the output.",
      "evidence": "note",
      "location": "operations[0].examples[0]",
      "agent_impact": "An agent may depend on a field the contract does not promise.",
      "suggested_fix": "Remove note from the example or declare it."
    },
    {
      "type": "example_schema_mismatch",
      "severity": "high",
      "description": "The supplied example JSON type does not match the supplied output schema. This is a conflict between the two documents, not a confirmed server defect.",
      "evidence": "string expected",
      "location": "operations[0].examples[0].id",
      "agent_impact": "An agent that trusts the example will send or expect a value the schema rejects.",
      "suggested_fix": "Change the example to type string or change the schema."
    },
    {
      "type": "example_schema_mismatch",
      "severity": "high",
      "description": "The supplied example is not one of the schema enum values.",
      "evidence": "\"shipped\"",
      "location": "operations[0].examples[0].status",
      "agent_impact": "An agent can treat an undocumented status as valid and then take the wrong branch.",
      "suggested_fix": "Use one of [\"draft\",\"submitted\"]."
    }
  ],
  "warnings": [],
  "recommendations": [],
  "limitations": [
    "Checks read only the supplied operations, workflows, and OpenAPI document. No URL is fetched and no model reads the text.",
    "A missing sentence is an undocumented contract. It is not a confirmed defect in a running implementation.",
    "A contradiction is two statements in the supplied text. It is not proof of how a server behaves.",
    "The HTTP method is not evidence that an operation is safe to retry or that it is idempotent.",
    "Matches are fixed phrases and field names. They do not infer a business rule that the text does not state.",
    "Comparison checks type, enum, required, additionalProperties false, array items, and nested objects. A local #/ pointer is followed inside the schema or the OpenAPI document.",
    "A mismatch means the supplied example and the supplied schema disagree. It does not prove a live server returned that body.",
    "The score is the percentage of examples with no mismatch. It is omitted when no pair was compared."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-contracts/output-contract-check" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "operations": [
    {
      "name": "create_order",
      "outputSchema": {
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "submitted"
            ]
          }
        }
      },
      "examples": [
        {
          "id": 15,
          "status": "shipped",
          "note": "rush"
        },
        {
          "id": "ord_1",
          "status": "draft"
        }
      ]
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-contracts/state-transition-check$0.04 USDC

Check state transition contracts

Find supplied workflow transitions that name an unknown state, two destinations for one trigger, or an operation that is not in the supplied list. Missing edges are undocumented, not proof a state is unreachable.

Body

Field	Required	Notes
`operations`	No	array; Array
`workflows`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "operations": [
    {
      "name": "create_order",
      "description": "Creates an order."
    }
  ],
  "workflows": [
    {
      "name": "order",
      "states": [
        "draft",
        "submitted",
        "paid"
      ],
      "transitions": [
        {
          "from": "draft",
          "to": "submitted",
          "on": "place",
          "operation": "create_order"
        },
        {
          "from": "draft",
          "to": "paid",
          "on": "place",
          "operation": "missing_op"
        },
        {
          "from": "submitted",
          "to": "archived",
          "on": "close"
        }
      ]
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Checked 1 workflows or operation texts that declare a transition.",
  "score": 48,
  "issues": [
    {
      "type": "unknown_operation",
      "severity": "medium",
      "description": "A transition names an operation that is not in the supplied operation list. The operation was not assumed to exist.",
      "evidence": "missing_op",
      "location": "workflows[0].transitions[1]",
      "agent_impact": "An agent can call an operation the contract bundle does not define.",
      "suggested_fix": "Point the transition at a supplied operation name."
    },
    {
      "type": "contradictory_transition",
      "severity": "high",
      "description": "The same state and trigger lead to two different states in the supplied workflow.",
      "evidence": "draft on place -> submitted and paid",
      "location": "workflows[0].transitions[1]",
      "agent_impact": "An agent cannot choose one next state for the same trigger.",
      "suggested_fix": "Keep one destination for that state and trigger."
    },
    {
      "type": "unknown_state",
      "severity": "high",
      "description": "A transition ends in a state that is not in the supplied state list.",
      "evidence": "archived",
      "location": "workflows[0].transitions[2]",
      "agent_impact": "An agent can record a state the rest of the contract does not mention.",
      "suggested_fix": "Add archived to states or change the transition."
    }
  ],
  "warnings": [
    {
      "type": "no_incoming",
      "severity": "low",
      "description": "No supplied transition enters this state. The contract does not identify it as the start.",
      "evidence": "draft",
      "location": "workflows[0]",
      "agent_impact": "An agent has no declared way to reach this state.",
      "suggested_fix": "Add the transition that enters it, or mark it as the start in the workflow text."
    },
    {
      "type": "no_outgoing",
      "severity": "low",
      "description": "No supplied transition leaves this state. The contract does not say it is terminal.",
      "evidence": "paid",
      "location": "workflows[0]",
      "agent_impact": "An agent may wait for a later state that is never defined, or it may stop early.",
      "suggested_fix": "Add the next transition, or state that this state is terminal."
    }
  ],
  "recommendations": [],
  "limitations": [
    "Checks read only the supplied operations, workflows, and OpenAPI document. No URL is fetched and no model reads the text.",
    "A missing sentence is an undocumented contract. It is not a confirmed defect in a running implementation.",
    "A contradiction is two statements in the supplied text. It is not proof of how a server behaves.",
    "The HTTP method is not evidence that an operation is safe to retry or that it is idempotent.",
    "Matches are fixed phrases and field names. They do not infer a business rule that the text does not state.",
    "Transitions come from workflow.transitions and from operation sentences that say from X to Y or X -> Y.",
    "An unknown operation is reported only when other operations were supplied and the name is absent. The check does not invent the missing operation.",
    "An unknown state or a trigger with two destinations is a conflict in the document. A state with no edge is a warning and does not change the score.",
    "Each unknown state subtracts 15. A contradictory trigger subtracts 25. An unknown operation subtracts 12. The score is omitted when no transition is declared."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-contracts/state-transition-check" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "operations": [
    {
      "name": "create_order",
      "description": "Creates an order."
    }
  ],
  "workflows": [
    {
      "name": "order",
      "states": [
        "draft",
        "submitted",
        "paid"
      ],
      "transitions": [
        {
          "from": "draft",
          "to": "submitted",
          "on": "place",
          "operation": "create_order"
        },
        {
          "from": "draft",
          "to": "paid",
          "on": "place",
          "operation": "missing_op"
        },
        {
          "from": "submitted",
          "to": "archived",
          "on": "close"
        }
      ]
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-contracts/partial-failure-check$0.04 USDC

Check partial failure contracts

Find multi-step workflows that do not say whether a later failure leaves earlier steps in place, rolls them back, or can be retried. Atomic and partial success in the same text is a contract contradiction.

Body

Field	Required	Notes
`operations`	No	array; Array
`workflows`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "workflows": [
    {
      "name": "checkout",
      "description": "Runs reserve, then charge, then notify.",
      "steps": [
        {
          "name": "reserve",
          "description": "Reserves stock."
        },
        {
          "name": "charge",
          "description": "Charges the card."
        },
        {
          "name": "notify",
          "description": "Sends the receipt."
        }
      ]
    },
    {
      "name": "refund",
      "description": "The refund is atomic and also reports partial success.",
      "steps": [
        {
          "name": "credit",
          "description": "Credits the payment."
        },
        {
          "name": "restock",
          "description": "Restocks the sku."
        }
      ]
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Checked 2 multi-step definitions for a partial result, rollback, and step retry.",
  "score": 43,
  "issues": [
    {
      "type": "missing_partial_result",
      "severity": "high",
      "description": "More than one step is declared, and the text does not say whether a later failure leaves earlier steps completed. That behavior is undocumented.",
      "evidence": "reserve, charge, notify",
      "location": "workflows[0]",
      "agent_impact": "An agent may retry the whole workflow after the first step has already completed, or it may ignore a step that failed.",
      "suggested_fix": "State whether a response lists a per-step status, or state that partial success cannot occur."
    },
    {
      "type": "missing_rollback",
      "severity": "medium",
      "description": "The multi-step contract does not say whether completed steps are rolled back, compensated, or left in place.",
      "evidence": "checkout",
      "location": "workflows[0]",
      "agent_impact": "An agent does not know whether it must undo an earlier step after a later step fails.",
      "suggested_fix": "Say the steps are atomic, or name the compensation step."
    },
    {
      "type": "contradictory_failure_mode",
      "severity": "high",
      "description": "The contract says the steps are atomic or all-or-nothing and also says a partial success is possible.",
      "evidence": "The refund is atomic and also reports partial success. credit Credits the payment. restock Restocks the sku.",
      "location": "workflows[1]",
      "agent_impact": "An agent cannot tell whether a failed step left earlier steps in place.",
      "suggested_fix": "Choose one mode and name the response field that shows which steps completed."
    }
  ],
  "warnings": [
    {
      "type": "missing_step_retry",
      "severity": "medium",
      "description": "The contract does not say whether a failed step can be retried without repeating the earlier steps.",
      "evidence": "checkout",
      "location": "workflows[0]",
      "agent_impact": "An agent may restart at step one after a later timeout.",
      "suggested_fix": "Say which step may be retried and which earlier result must be reused."
    },
    {
      "type": "missing_step_retry",
      "severity": "medium",
      "description": "The contract does not say whether a failed step can be retried without repeating the earlier steps.",
      "evidence": "refund",
      "location": "workflows[1]",
      "agent_impact": "An agent may restart at step one after a later timeout.",
      "suggested_fix": "Say which step may be retried and which earlier result must be reused."
    }
  ],
  "recommendations": [],
  "limitations": [
    "Checks read only the supplied operations, workflows, and OpenAPI document. No URL is fetched and no model reads the text.",
    "A missing sentence is an undocumented contract. It is not a confirmed defect in a running implementation.",
    "A contradiction is two statements in the supplied text. It is not proof of how a server behaves.",
    "The HTTP method is not evidence that an operation is safe to retry or that it is idempotent.",
    "Matches are fixed phrases and field names. They do not infer a business rule that the text does not state.",
    "A multi-step definition is two or more workflow or operation steps, or the words batch, bulk, multi-step, or each item.",
    "Partial phrases include partial success, per-item, and item status. Rollback phrases include rollback, compensate, undo, atomic, and all-or-nothing.",
    "A contradiction subtracts 25. A missing partial result subtracts 20. A missing rollback sentence subtracts 12. A missing step retry is a warning.",
    "The score is omitted when the document does not describe more than one step."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-contracts/partial-failure-check" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "workflows": [
    {
      "name": "checkout",
      "description": "Runs reserve, then charge, then notify.",
      "steps": [
        {
          "name": "reserve",
          "description": "Reserves stock."
        },
        {
          "name": "charge",
          "description": "Charges the card."
        },
        {
          "name": "notify",
          "description": "Sends the receipt."
        }
      ]
    },
    {
      "name": "refund",
      "description": "The refund is atomic and also reports partial success.",
      "steps": [
        {
          "name": "credit",
          "description": "Credits the payment."
        },
        {
          "name": "restock",
          "description": "Restocks the sku."
        }
      ]
    }
  ]
}
JSON