Find Similar Files

Local and remote matching

Find Similar Files lets you submit source identifiers, such as DOIs or open access IDs, and search for the corresponding file locally and through remote bibliographic sources such as Arxiv and PubMed.

If a remote bibliographic record is found but the full file is not available as open access, the API returns a metadataOnly match. This lets you keep the bibliographic match even when there is no file to download or index.

How It Works

Find-similar runs as an asynchronous job. The job starts from source identifiers, checks indexed local files, searches remote bibliographic sources, and returns a unified result grouped by source.

For each source, the result can contain:

• files: local indexed files that match the source.
• metadataOnly: remote bibliographic matches where no open access file is available.

Creating a Find-Similar Job

cURL

curl -X POST "https://<api-domain>/api/core/find-similar/jobs" \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIdentifiers": [
      { "doi": "10.1000/example" },
      { "id": "35930681" },
      { "openAccessId": "PMC1234567" }
    ]
  }'

Python (httpx)

response = client.post(
    "/find-similar/jobs",
    json={
        "sourceIdentifiers": [
            {"doi": "10.1000/example"},
            {"id": "35930681"},
            {"openAccessId": "PMC1234567"},
        ]
    },
)
response.raise_for_status()

job = response.json()
print(f"Job created: {job['jobId']} ({job['status']})")

R

resp <- base_req |>
  req_url_path_append("find-similar", "jobs") |>
  req_body_json(list(
    sourceIdentifiers = list(
      list(doi = "10.1000/example"),
      list(id = "35930681"),
      list(openAccessId = "PMC1234567")
    )
  )) |>
  req_perform()

job <- resp_body_json(resp)
cat(sprintf("Job created: %s (status: %s)\n", job$jobId, job$status))

SDK

import asyncio
from biolevate import BiolevateClient, SourceIdentifiers

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        job = await client.find_similar.create_job(
            source_identifiers=[
                SourceIdentifiers(doi="10.1000/example"),
                SourceIdentifiers(id="35930681"),
                SourceIdentifiers(open_access_id="PMC1234567"),
            ]
        )
        print(f"Job created: {job.job_id} (status: {job.status})")

asyncio.run(main())

Source Identifiers

Each item in sourceIdentifiers can contain one or more identifiers:

Field	Description
doi	DOI for the source publication (e.g. 10.1000/example)
id	Pubmed or Arxiv identifier (e.g. 35930681)
openAccessId	Open access or repository identifier (e.g. PMC1234567)

Polling and Reading Results

curl -s "https://<api-domain>/api/core/find-similar/jobs/${JOB_ID}" \
  -H "Authorization: Bearer <your-pat>"

Completed jobs return:

Field	Description
sources	Original submitted source identifiers
result	List of SourceMatches, grouped by source
statistics	Counts for queried, matched, unmatched, and failed sources

Each SourceMatches item contains:

Field	Description
source	Source identifier being matched
files	Local indexed file matches
metadataOnly	Remote Arxiv/PubMed-style bibliographic matches where the file is not available as open access

Listing Jobs

curl -s "https://<api-domain>/api/core/find-similar/jobs?page=0&pageSize=20" \
  -H "Authorization: Bearer <your-pat>"

SDK Polling Example

import asyncio
from biolevate import BiolevateClient, SourceIdentifiers

TERMINAL_STATUSES = {"COMPLETED", "FAILED"}

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        job = await client.find_similar.create_job(
            source_identifiers=[SourceIdentifiers(doi="10.1000/example")]
        )

        while True:
            job = await client.find_similar.get_job(job.job_id)
            if job.status in TERMINAL_STATUSES:
                break
            await asyncio.sleep(3)

        if job.status == "COMPLETED":
            print(job.statistics)
            for source_match in job.result or []:
                for file_match in source_match.files or []:
                    print(f"Local file: {file_match.name} ({file_match.path})")
                for metadata_match in source_match.metadata_only or []:
                    print(f"Remote metadata-only result: {metadata_match.search_result_id}")

asyncio.run(main())

Next Steps

• Python SDK: Find Similar Files — high-level SDK methods
• Files — index files so they can be matched locally
• API Reference for complete schemas