# Protein Structure Release Monitor (`flintglade/protein-structure-release-monitor`) Actor

Monitor protein structure releases and revisions across RCSB PDB, PDBe, AlphaFold DB, and UniProt with durable baselines and evidence-backed diffs.

- **URL**: https://apify.com/flintglade/protein-structure-release-monitor.md
- **Developed by:** [Flintglade](https://apify.com/flintglade) (community)
- **Categories:** Automation, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $30.00 / 1,000 target checks

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Protein Structure Release Monitor

Monitor named protein targets for added, revised, obsoleted, replaced, or confirmed-removed experimental structures and existing predicted models.

### What this does not do

- No target discovery.
- No interpretation of biological significance.
- No single-check removal declaration.
- No docking or medical claims.
- No coordinate download by default.
- No independent source crawling.
- No structure prediction. AlphaFold DB rows are existing provider records and are always labeled `predicted`; PDB rows are always labeled `experimental`.

### Official sources

The Actor makes bounded GET requests only to official RCSB PDB Search/Data API, PDBe API v2, AlphaFold DB API, and UniProt REST entry endpoints. It does not accept user URLs or credentials. `SOURCE_POLICY.md` records the exact endpoints, authority, attribution, and failure semantics.

RCSB and PDBe catalogs are reconciled before experimental additions become material changes. An ID visible in only one catalog is reported under `catalogChurn` and is not treated as an addition or removal.

### Input

Each target contains exactly one `uniprotId`, `pdbId`, or `alphaFoldId`. A persistent run also requires a user-selected `baselineStoreId`.

```json
{
  "targets": [{"uniprotId": "P69905"}],
  "mode": "stateless",
  "includeExperimental": true,
  "includePredicted": true,
  "includeLigands": true,
  "concurrency": 1
}
````

`removalConfirmationHours` defaults to and cannot be lower than 6. `concurrency` defaults to 4 and cannot exceed 8. A run accepts 1–500 unique targets. At least one of experimental or predicted evidence must be enabled.

### Output

The default dataset receives one bounded result row per completed target and one uncharged run-summary row. A typical result contains:

```json
{
  "recordType": "result",
  "schemaVersion": "1.0.0",
  "status": "changed",
  "finding": "material structure evidence changed",
  "charge": {"event": "target-check", "priceUsd": 0.03, "chargeable": true},
  "evidenceSummary": {
    "uniprotAccession": "P69905",
    "experimentalCount": 12,
    "predictedCount": 1,
    "obsoleteOrReplacedCount": 0
  },
  "changes": [{"changeClass": "ligand_set_changed", "recordId": "4HHB"}]
}
```

Change records use stable classes: `new_structure`, `metadata_revised`, `sequence_mapping_changed`, `ligand_set_changed`, `confidence_changed`, `model_version_changed`, `obsolete`, `replaced`, `missing_unconfirmed`, and `removed_confirmed`. Every change includes exact normalized field paths and official-source locators. Full snapshots and detailed diffs remain in the named baseline store or KVS artifact rather than a multi-megabyte dataset cell. `ARTIFACT_MANIFEST.json` records content type, byte length, SHA-256, schema version, and generation rule.

### Pricing

The primary pay-per-event event is exactly `target-check` at **$0.03 per target check**. Maximum event cost is `number of targets × $0.03`; for 100 targets the maximum is $3.00, subject to the platform charge cap.

Baseline creation, unchanged checks, material changes, official obsolete/replaced states, confirmed removals, and completed no-evidence checks are chargeable. Invalid targets, mapping failures, source outages, rate-limit exhaustion, parse failures, and first unconfirmed missing observations are not charged. The synthetic `apify-default-dataset-item` event must remain disabled.

### Baseline and removal behavior

Persistent mode uses the caller-selected KVS. For chargeable results the Actor writes a `PREPARED` journal, pushes exactly one `target-check`, verifies `charged_count == 1`, then writes immutable history and swaps the canonical baseline. A zero charge, outage, failure, or charge cap never advances the baseline.

Absence is not removal. The first successful missing observation is uncharged, updates only a separate missing journal, and leaves the canonical baseline intact. The same missing-record set must be observed by successful provider checks at least six hours later before `removed_confirmed`. Restoration clears the journal after a charged successful check. An official PDBe obsolete/replacement state is evidence and does not require the two-observation delay.

### Partial failures and negative results

An HTTP 404/410 from the exact entry endpoint is a terminal source fact only where the contract permits it. Timeouts, 429 responses, malformed 200 responses, response limits, redirects outside official hosts, and provider disagreements are never converted into missing evidence. Any requested provider outage makes the target row uncharged and leaves all monitor state unchanged.

### Resources

Candidate resources are minimum 256 MB, default 1024 MB, maximum 2048 MB, with a 600-second hosted timeout. Source JSON is capped at 8 MB and depth 40. RCSB catalogs are bounded at 1,000 identifiers; if truncated, removals are disabled and prior records are carried forward.

### Data handling, privacy, and deletion

Inputs contain public protein identifiers and a caller-selected Apify KVS reference. No credentials or user URLs are accepted. Raw provider bodies are hashed in memory and are not retained. Dataset rows contain normalized public metadata and redacted input. Delete the run dataset/default KVS and the selected baseline KVS through Apify to remove stored results and history. See `PRIVACY.md`.

### Source rights and attribution

Results preserve provider names and evidence URLs. Source data remains subject to RCSB PDB, PDBe/EMBL-EBI, AlphaFold DB, and UniProt terms and attribution requirements. The Actor does not transfer ownership or certify downstream rights. See `SOURCE_POLICY.md`.

### Limitations

Catalog releases are asynchronous, provider fields can drift, and a catalog cap can delay change recognition. Confidence changes are provider-reported metadata changes, not biological interpretation. Coverage is a deterministic residue-range summary against the exact UniProt sequence identity; no structural alignment or quality ranking is performed.

### Support and changelog

See `SUPPORT.md` for support and `CHANGELOG.md` for version history.

# Actor input Schema

## `inputSchemaVersion` (type: `integer`):

Version of the strict runtime contract.

## `targets` (type: `array`):

Each target must contain exactly one UniProt accession, PDB identifier, or AlphaFold DB model identifier.

## `mode` (type: `string`):

Persistent mode compares and commits a named baseline only after an accepted charge.

## `baselineStoreId` (type: `string`):

Required only in persistent mode. First missing observations update a separate journal, never this canonical baseline.

## `includeExperimental` (type: `boolean`):

Include experimentally determined PDB records from reconciled RCSB and PDBe catalogs.

## `includePredicted` (type: `boolean`):

Include existing AlphaFold DB models as predicted evidence; no prediction is performed.

## `includeLigands` (type: `boolean`):

Include source-reported CCD ligand identifiers for experimental records.

## `removalConfirmationHours` (type: `integer`):

Minimum elapsed time between two successful matching missing observations. Cannot be lowered below six hours.

## `concurrency` (type: `integer`):

Maximum targets processed concurrently; per-source requests remain independently bounded.

## Actor input object example

```json
{
  "inputSchemaVersion": 1,
  "targets": [
    {
      "uniprotId": "P69905"
    }
  ],
  "mode": "stateless",
  "includeExperimental": true,
  "includePredicted": true,
  "includeLigands": true,
  "removalConfirmationHours": 6,
  "concurrency": 4
}
```

# Actor output Schema

## `defaultDataset` (type: `string`):

No description

## `artifacts` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "targets": [
        {
            "uniprotId": "P69905"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("flintglade/protein-structure-release-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "targets": [{ "uniprotId": "P69905" }] }

# Run the Actor and wait for it to finish
run = client.actor("flintglade/protein-structure-release-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "targets": [
    {
      "uniprotId": "P69905"
    }
  ]
}' |
apify call flintglade/protein-structure-release-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=flintglade/protein-structure-release-monitor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Protein Structure Release Monitor",
        "description": "Monitor protein structure releases and revisions across RCSB PDB, PDBe, AlphaFold DB, and UniProt with durable baselines and evidence-backed diffs.",
        "version": "0.1",
        "x-build-id": "eYiRtQqKnFdSJ2CJH"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/flintglade~protein-structure-release-monitor/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-flintglade-protein-structure-release-monitor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/flintglade~protein-structure-release-monitor/runs": {
            "post": {
                "operationId": "runs-sync-flintglade-protein-structure-release-monitor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/flintglade~protein-structure-release-monitor/run-sync": {
            "post": {
                "operationId": "run-sync-flintglade-protein-structure-release-monitor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "targets"
                ],
                "properties": {
                    "inputSchemaVersion": {
                        "title": "Input schema version",
                        "minimum": 1,
                        "maximum": 1,
                        "type": "integer",
                        "description": "Version of the strict runtime contract.",
                        "default": 1
                    },
                    "targets": {
                        "title": "Protein targets",
                        "minItems": 1,
                        "maxItems": 500,
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Each target must contain exactly one UniProt accession, PDB identifier, or AlphaFold DB model identifier.",
                        "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "uniprotId": {
                                    "title": "UniProt accession",
                                    "description": "One canonical UniProtKB accession such as P69905.",
                                    "type": "string",
                                    "minLength": 6,
                                    "maxLength": 10,
                                    "pattern": "^(?:[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9](?:[A-Z][A-Z0-9]{2}){1,2}[0-9])$"
                                },
                                "pdbId": {
                                    "title": "PDB identifier",
                                    "description": "One four-character PDB entry identifier such as 4HHB.",
                                    "type": "string",
                                    "minLength": 4,
                                    "maxLength": 4,
                                    "pattern": "^[0-9][A-Z0-9]{3}$"
                                },
                                "alphaFoldId": {
                                    "title": "AlphaFold DB model",
                                    "description": "One existing AlphaFold DB model identifier such as AF-P69905-F1.",
                                    "type": "string",
                                    "minLength": 12,
                                    "maxLength": 18,
                                    "pattern": "^AF-[A-Z0-9]{6,10}-F[1-9][0-9]*$"
                                }
                            }
                        }
                    },
                    "mode": {
                        "title": "Monitoring mode",
                        "enum": [
                            "stateless",
                            "persistent"
                        ],
                        "type": "string",
                        "description": "Persistent mode compares and commits a named baseline only after an accepted charge.",
                        "default": "stateless"
                    },
                    "baselineStoreId": {
                        "title": "Baseline key-value store",
                        "minLength": 1,
                        "maxLength": 128,
                        "type": "string",
                        "description": "Required only in persistent mode. First missing observations update a separate journal, never this canonical baseline."
                    },
                    "includeExperimental": {
                        "title": "Experimental structures",
                        "type": "boolean",
                        "description": "Include experimentally determined PDB records from reconciled RCSB and PDBe catalogs.",
                        "default": true
                    },
                    "includePredicted": {
                        "title": "Predicted models",
                        "type": "boolean",
                        "description": "Include existing AlphaFold DB models as predicted evidence; no prediction is performed.",
                        "default": true
                    },
                    "includeLigands": {
                        "title": "Ligand identifiers",
                        "type": "boolean",
                        "description": "Include source-reported CCD ligand identifiers for experimental records.",
                        "default": true
                    },
                    "removalConfirmationHours": {
                        "title": "Removal confirmation interval",
                        "minimum": 6,
                        "maximum": 720,
                        "type": "integer",
                        "description": "Minimum elapsed time between two successful matching missing observations. Cannot be lowered below six hours.",
                        "default": 6
                    },
                    "concurrency": {
                        "title": "Target concurrency",
                        "minimum": 1,
                        "maximum": 8,
                        "type": "integer",
                        "description": "Maximum targets processed concurrently; per-source requests remain independently bounded.",
                        "default": 4
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```