# Submit a new Math seed or topic

POST /api/math/seed-submissions

**Required scope:** `write`. **Roles:** Owner, Admin.

Saves a new pending research proposition in AWS. Maximum JSON body: 320 KiB. Does not start evaluation, create tasks/reports, or appear in the current dashboard UI. A pipeline operator must launch it separately using question_id and proposition. Supply a fresh client_request_id UUID for each intended submission; a retry with identical trimmed content returns 200 and the same record. Reuse with different content returns 409 seed_submission_conflict. Retries deduplicate per member across keys. Title is trimmed and must have 1–200 characters without controls; proposition is trimmed, 10–50,000 characters, allowing tabs and newlines but no other controls. Submission records cannot yet be edited, deleted or launched through this API.

Examples use synthetic data. This is a complete OpenAPI document for this operation, including required schemas.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Submit a new Math seed or topic",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://math-api.qmindlabs.ai",
      "description": "Main Math API"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/api/math/seed-submissions": {
      "post": {
        "tags": [
          "Seeds & topics"
        ],
        "summary": "Submit a new Math seed or topic",
        "operationId": "post__api_math_seed_submissions",
        "description": "**Required scope:** `write`. **Roles:** Owner, Admin.\n\nSaves a new pending research proposition in AWS. Maximum JSON body: 320 KiB. Does not start evaluation, create tasks/reports, or appear in the current dashboard UI. A pipeline operator must launch it separately using question_id and proposition. Supply a fresh client_request_id UUID for each intended submission; a retry with identical trimmed content returns 200 and the same record. Reuse with different content returns 409 seed_submission_conflict. Retries deduplicate per member across keys. Title is trimmed and must have 1–200 characters without controls; proposition is trimmed, 10–50,000 characters, allowing tabs and newlines but no other controls. Submission records cannot yet be edited, deleted or launched through this API.",
        "x-required-scopes": [
          "write"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Idempotent replay of an existing submission",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SeedSubmissionDetail"
                },
                "example": {
                  "submission": {
                    "id": "11111111-2222-4333-8444-555555555555",
                    "question_id": "api-11111111-2222-4333-8444-555555555555",
                    "client_request_id": "11111111-2222-4333-8444-555555555555",
                    "title": "Prime divisors of a square plus one",
                    "created_by": 42,
                    "api_key_id": null,
                    "created_at": "2026-09-22T12:00:00.000Z",
                    "status": "PENDING",
                    "evaluation_started": false,
                    "proposition": "Prove that every odd prime divisor of n squared plus one is congruent to one modulo four."
                  }
                }
              }
            }
          },
          "201": {
            "description": "Created successfully",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SeedSubmissionDetail"
                },
                "example": {
                  "submission": {
                    "id": "11111111-2222-4333-8444-555555555555",
                    "question_id": "api-11111111-2222-4333-8444-555555555555",
                    "client_request_id": "11111111-2222-4333-8444-555555555555",
                    "title": "Prime divisors of a square plus one",
                    "created_by": 42,
                    "api_key_id": null,
                    "created_at": "2026-09-22T12:00:00.000Z",
                    "status": "PENDING",
                    "evaluation_started": false,
                    "proposition": "Prove that every odd prime divisor of n squared plus one is congruent to one modulo four."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "invalid_request",
                  "message": "Invalid input"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked API key",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "invalid_api_key",
                  "message": "Missing, invalid, expired or revoked API key"
                }
              }
            }
          },
          "403": {
            "description": "Role, scope, account or origin does not permit this operation",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "api_key_scope_required",
                  "message": "Role, scope, account or origin does not permit this operation"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable or outside your permitted tasks",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "not_found",
                  "message": "Resource unavailable or outside your permitted tasks"
                }
              }
            }
          },
          "405": {
            "description": "HTTP method is not supported",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "method_not_allowed",
                  "message": "HTTP method is not supported"
                }
              }
            }
          },
          "409": {
            "description": "Stale version, invalid workflow transition or changed evidence; read the latest state before retrying",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "math_workflow_conflict",
                  "message": "Stale version, invalid workflow transition or changed evidence; read the latest state before retrying"
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds the permitted upload or JSON size",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "payload_too_large",
                  "message": "Request exceeds the permitted upload or JSON size"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported request Content-Type",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "json_required",
                  "message": "Unsupported request Content-Type"
                }
              }
            }
          },
          "429": {
            "description": "600 authenticated requests per minute per key exceeded; retry next minute",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "api_key_rate_limited",
                  "message": "600 authenticated requests per minute per key exceeded; retry next minute"
                }
              }
            }
          },
          "503": {
            "description": "Service, storage or capacity temporarily unavailable",
            "headers": {
              "x-request-id": {
                "description": "Server-generated identifier for tracing this request.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "service_unavailable",
                  "message": "Service, storage or capacity temporarily unavailable"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SeedSubmissionCreate"
              },
              "example": {
                "client_request_id": "11111111-2222-4333-8444-555555555555",
                "title": "Prime divisors of a square plus one",
                "proposition": "Prove that every odd prime divisor of n squared plus one is congruent to one modulo four."
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Math API key",
        "description": "Paste your issued key, without the Bearer prefix. No key is embedded in this documentation."
      }
    },
    "schemas": {
      "SeedSubmissionDetail": {
        "type": "object",
        "properties": {
          "submission": {
            "$ref": "#/components/schemas/SeedSubmission"
          }
        },
        "required": [
          "submission"
        ],
        "additionalProperties": false
      },
      "SeedSubmission": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "11111111-2222-4333-8444-555555555555"
          },
          "question_id": {
            "type": "string",
            "example": "api-11111111-2222-4333-8444-555555555555"
          },
          "client_request_id": {
            "type": "string",
            "format": "uuid",
            "example": "11111111-2222-4333-8444-555555555555"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "example": "Prime divisors of a square plus one"
          },
          "created_by": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991,
            "example": 42
          },
          "api_key_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[0-9a-f]{24}$",
                "example": "bbbbbbbbbbbbbbbbbbbbbbbb"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-22T12:00:00.000Z"
          },
          "status": {
            "type": "string",
            "const": "PENDING"
          },
          "evaluation_started": {
            "type": "boolean",
            "const": false
          },
          "proposition": {
            "type": "string",
            "minLength": 10,
            "maxLength": 50000,
            "example": "Prove that every odd prime divisor of n squared plus one is congruent to one modulo four."
          }
        },
        "required": [
          "id",
          "question_id",
          "client_request_id",
          "title",
          "created_by",
          "api_key_id",
          "created_at",
          "status",
          "evaluation_started",
          "proposition"
        ],
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "api_key_scope_required"
          },
          "message": {
            "type": "string",
            "example": "This operation requires the read scope."
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "SeedSubmissionCreate": {
        "type": "object",
        "properties": {
          "client_request_id": {
            "type": "string",
            "format": "uuid",
            "example": "11111111-2222-4333-8444-555555555555",
            "description": "Generate once per intended submission. Retries must reuse this UUID and the same trimmed title/proposition. Deduplication is per Math member, including across that member’s keys."
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "example": "Prime divisors of a square plus one"
          },
          "proposition": {
            "type": "string",
            "minLength": 10,
            "maxLength": 50000,
            "example": "Prove that every odd prime divisor of n squared plus one is congruent to one modulo four."
          }
        },
        "required": [
          "client_request_id",
          "title",
          "proposition"
        ],
        "additionalProperties": false
      }
    }
  }
}
```
