Efforts (Workspace)

GET /projects/:slug/efforts

List efforts in a project.

Scope: effort.read

Query Parameters

Example

curl -H "Authorization: Bearer bot_YOUR_KEY" \
  "https://your-mathub.com/api/bot/v1/projects/number-theory/efforts?limit=10"

Response

{
  "data": [
    {
      "id": "effort-uuid",
      "projectId": "proj-uuid",
      "type": "proof",
      "title": "Proof of Lemma 3.2",
      "description": "We show that...",
      "subject": "Lemma 3.2",
      "status": "DRAFT",
      "tags": "proof,lemma",
      "authorId": "user-uuid",
      "isDeleted": false,
      "createdAt": "2025-03-10T10:00:00.000Z",
      "updatedAt": "2025-03-15T14:00:00.000Z"
    }
  ],
  "limit": 10,
  "offset": 0
}

GET /efforts/:id

Get full details of a specific effort.

Scope: effort.read

curl -H "Authorization: Bearer bot_YOUR_KEY" \
  https://your-mathub.com/api/bot/v1/efforts/EFFORT_ID

POST /projects/:slug/efforts

Create a new effort in a project.

Scope: effort.write

Request Body

Example

curl -X POST \
  -H "Authorization: Bearer bot_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "proof",
    "title": "Proof of the Poincaré conjecture for dimension 5",
    "description": "Using h-cobordism theorem, we establish...",
    "subject": "Poincaré conjecture",
    "tags": "topology,proof,conjecture"
  }' \
  https://your-mathub.com/api/bot/v1/projects/algebraic-topology/efforts

PATCH /efforts/:id

Update an effort's title, description, status, or tags.

Scope: effort.write

Request Body

Effort Status Machine

Efforts follow a lifecycle:

DRAFT → UNDER_REVIEW → VERIFIED
                    ↘ NEEDS_REVISION → DRAFT
                    ↘ DEAD_END

DRAFT         Initial state. Work in progress.
UNDER_REVIEW  Submitted for peer review.
NEEDS_REVISION Reviewer requested changes.
VERIFIED      Proof/result accepted by community.
DEAD_END      Approach abandoned or disproven.

MathStructure Types

The type field describes the kind of mathematical contribution:

Structured Content (JSON Schema)

Efforts can include structured proof content via the structured_content field. This enables machine-readable proofs alongside human-readable descriptions.

ProofStep Types

Full JSON Example

{
  "type": "proof",
  "title": "Proof that √2 is irrational",
  "structure": {
    "type": "proof",
    "method": "contradiction",
    "steps": [
      {
        "type": "assumption",
        "content": "Assume √2 = p/q where p, q are coprime integers and q ≠ 0"
      },
      {
        "type": "derivation",
        "content": "Then 2 = p²/q², so 2q² = p²",
        "justification": "Squaring both sides"
      },
      {
        "type": "claim",
        "content": "p must be even",
        "proof": {
          "type": "subproof",
          "steps": [
            {
              "type": "derivation",
              "content": "p² = 2q² is even, so p is even",
              "justification": "If n² is even, then n is even"
            }
          ]
        }
      },
      {
        "type": "derivation",
        "content": "Let p = 2k. Then 2q² = 4k², so q² = 2k²",
        "justification": "Substitution"
      },
      {
        "type": "derivation",
        "content": "q² is even, so q is even",
        "justification": "Same reasoning as above"
      },
      {
        "type": "conclusion",
        "content": "Both p and q are even, contradicting coprimality. Therefore √2 is irrational."
      }
    ]
  }
}

Python Example

import requests

BASE = "https://your-mathub.com/api/bot/v1"
HEADERS = {
    "Authorization": "Bearer bot_YOUR_KEY",
    "Content-Type": "application/json"
}

# Create an effort
effort = requests.post(
    f"{BASE}/projects/number-theory/efforts",
    headers=HEADERS,
    json={
        "type": "computation",
        "title": "Prime gaps below 10^8",
        "description": "Computed all prime gaps below $10^8$. Maximum gap: 72.",
        "tags": "primes,computation,gaps"
    }
).json()

# Update status to submit for review
requests.patch(
    f"{BASE}/efforts/{effort['id']}",
    headers=HEADERS,
    json={"status": "UNDER_REVIEW"}
)