API Reference

This guide covers the TPL API for guardians and developers who contribute signal entries. It documents the end-to-end flow for discovering signals, fetching project data, and submitting scores.

Prerequisites

Admin API token with TPL endpoint permissions
Network access to https://staging.core.api.thrive.xyz (or production URL)
Optional: Local scoring scripts for automated evaluation

Authentication

All requests require the X-API-KEY header:

X-API-KEY: YOUR-API-TOKEN

Replace YOUR-API-TOKEN with your scoped admin token.

Endpoints

List Signals

Retrieve all available signals with their rubrics and scoring instructions.

GET /tpl/signals

Response:

json

{
  "success": true,
  "data": {
    "signals": [
      {
        "id": 1,
        "key": "educational_experience",
        "rubric_mappings": { ... },
        "review_instructions": "..."
      }
    ]
  }
}

Use rubric_mappings to understand scoring criteria. Use review_instructions for manual evaluation guidance.

Get Missing Entries

Retrieve projects that need scoring for a specific signal.

GET /tpl/signals/{signal_id}/signal_entries/missing

Response:

json

[
  {
    "project_id": 596,
    "subject_type": "UserProject",
    "subject_id": 598
  },
  {
    "project_id": 599,
    "subject_type": "UserProject",
    "subject_id": 603
  }
]

This is your work queue. Process each project_id to collect evidence and submit scores.

Get missing signal entries

GET /tpl/missing_signal_entries

Response:

json

{
    "message": "",
    "success": true,
    "data": {
        "missing_signal_entries": [
            {
                "id": 31,
                "tpl_signal": {
                    "id": 6,
                    "key": "active_wallets_growth",
                    "category": "onchain_traction",
                    "name": "Active User Wallets - 7d/30d Growth Rate",
                    "rubric_mappings": {
                        "1": "\u003c -30%",
                        "2": "-30% to -10%",
                        "3": "-10% to 20%",
                        "4": "20% to 50%",
                        "5": "\u003e 50%"
                    },
                    "review_instructions": "Access blockchain explorer for the protocol's smart contracts. Count unique wallet addresses that interacted in last 7 days vs previous 30 days. Apply proof-of-humanity filters to exclude bot wallets (irregular timing, varying amounts, diverse interactions). Exclude addresses with bot-like behavior (identical timing, same amounts, sequential patterns). Calculate growth rate and refer to Manual Verification Methods for Onchain Metrics for detailed bot detection techniques.",
                    "subject_entity": null
                },
                "project": {
                    "id": 604,
                    "name": "HackerMan",
                    "logo_url": "...",
                    "url": "http://github.com"
                },
                "subject": null
            }
        ]
    }
}

Parameters

Parameter	Type	Required	Description	Example Value
`project_id`	integer	Optional	Unique identifier for the project	`604`
`tpl_signal_id[]`	array	Optional	Template signal ID(s). Use `%5B%5D` for URL encoding or `[]` for multiple values	`1`
`category`	string	Optional	Filter by category type	`team_credibility`

Example URL:

/tpl/missing_signal_entries?project_id=604&tpl_signal_id%5B%5D=1&category=team_credibility

Get Project Details

Retrieve full project information including team members and metadata.

GET /tpl/projects/{project_id}/details

Response:

json

{
  "data": {
    "project": {
      "id": 599,
      "name": "Project Name",
      "user_projects": [
        {
          "subject_id": 603,
          "first_name": "Alice",
          "linkedin_url": "https://linkedin.com/in/alice"
        }
      ],
      "project_github_urls": [...],
      "project_smart_contracts": [...]
    }
  }
}

Use user_projects for team credibility signals. Each entry has a subject_id for individual scoring.

Submit Signal Entry

Submit a score for a project or subject.

POST /tpl/signals/{signal_id}/signal_entries

Request body:

json

{
  "signal_entry": {
    "project_id": 599,
    "score": 5,
    "notes": "Evidence: LinkedIn shows 5 years as CEO at 50-person company",
    "subject_id": 603,
    "subject_type": "UserProject",
    "metrics": {
      ...
    }
  }
}

Fields:

Field	Required	Description
`project_id`	Yes	The project being scored
`score`	Yes	Score value (typically 1-5)
`notes`	Yes	Evidence and rationale
`subject_id`	No	Individual subject ID (for per-person signals)
`subject_type`	No	Subject type, e.g., "UserProject"

For project-level signals (no per-subject data), set subject_id and subject_type to null.

For different signals we support different metrics those are listed down below.

Supported Metric Fields:

Signal Key	Supported Metrics	Description
`educational_experience`	`ranking_of_university`	The university rank
`commit_frequency`	`number_of_commits`	Number of commits on the project repos
`active_contributors`	`number_of_contributors`	Number of active contributors on the project repos
`repo_stars`	`number_of_github_stars`	Number of github repo stars on the project repos

Workflow

1. Discover Signals

bash

curl -H "X-API-KEY: $API_TOKEN" \
  "https://staging.core.api.thrive.xyz/tpl/signals"

Review the response to select which signal to process. Note the id, rubric_mappings, and review_instructions.

2. Fetch Missing Entries

bash

curl -H "X-API-KEY: $API_TOKEN" \
  "https://staging.core.api.thrive.xyz/tpl/signals/1/signal_entries/missing"

Save the response as your work queue.

3. Get Project Details

For each project in your queue:

bash

curl -H "X-API-KEY: $API_TOKEN" \
  "https://staging.core.api.thrive.xyz/tpl/projects/599/details"

Extract user_projects for team credibility signals. Collect evidence from LinkedIn, GitHub, and other sources listed in the response.

4. Score the Subject

Apply the rubric from review_instructions:

For team credibility: evaluate each team member against the scoring criteria
For product execution: pull GitHub metrics and apply thresholds
For GDP metrics: verify onchain data against scoring bands

5. Submit the Score

bash

curl -X POST \
  -H "X-API-KEY: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "signal_entry": {
      "project_id": 599,
      "score": 5,
      "notes": "LinkedIn verified. CEO at 50-person company for 3 years.",
      "subject_id": 603,
      "subject_type": "UserProject"
    }
  }' \
  "https://staging.core.api.thrive.xyz/tpl/signals/1/signal_entries"

Log the response for auditing.

6. Monitor and Verify

After submitting scores:

Check for API errors (4xx/5xx responses)
Validate a sample of submitted scores in the UI
Monitor downstream jobs triggered by new entries

Best Practices

Dry-run first: Fetch missing entries and project details without POSTing. Verify your scoring logic before submitting.

Start with a canary: Process 5-10 projects first. Validate results before scaling to the full queue.

Rate limiting: Limit POST requests to 30-120 per minute depending on API capacity.

Include evidence: Always add verification links in the notes field. Future reviewers need to audit your work.

Audit logging: Keep a local log (CSV or JSON) of all submissions:

project_id, subject_id
score, timestamp
Request and response bodies

Idempotency: If the backend supports idempotency keys, include them to prevent duplicate submissions.

Error Handling

Transient errors (5xx): Retry with exponential backoff. Start at 1 second, double on each retry, cap at 60 seconds.

Validation errors (4xx): Inspect the response body. Common issues:

Invalid subject_id for the given project
Score outside allowed range
Missing required fields

Error patterns: If you see many 4xx/5xx responses, pause and escalate to the backend team before continuing.

Team Credibility Scoring

For signals in the team_credibility category (e.g., educational_experience, leadership_experience):

Fetch project details to get user_projects array
Each entry has a subject_id representing a team member
Follow review_instructions for the signal (duration thresholds, title mappings, company size requirements)
Submit one signal_entry per team member

Rollback

If you need to undo submitted entries:

Use your audit log to identify created entries
Contact the backend team for bulk reversion
If the API supports DELETE, use it with the entry IDs from your log

Always maintain audit logs to enable rollback when needed.

API Reference ​

Prerequisites ​

Authentication ​

Endpoints ​

List Signals ​

Get Missing Entries ​

Get missing signal entries ​

Parameters ​

Get Project Details ​

Submit Signal Entry ​

Workflow ​

1. Discover Signals ​

2. Fetch Missing Entries ​

3. Get Project Details ​

4. Score the Subject ​

5. Submit the Score ​

6. Monitor and Verify ​

Best Practices ​

Error Handling ​

Team Credibility Scoring ​

Rollback ​

API Reference

Prerequisites

Authentication

Endpoints

List Signals

Get Missing Entries

Get missing signal entries

Parameters

Get Project Details

Submit Signal Entry

Workflow

1. Discover Signals

2. Fetch Missing Entries

3. Get Project Details

4. Score the Subject

5. Submit the Score

6. Monitor and Verify

Best Practices

Error Handling

Team Credibility Scoring

Rollback