DevToolsDocs
DevToolsDocs
DashboardAPI Healthtimmit.dev
Beta

Integration Intelligence API

Integration Intelligence provides asynchronous repository analysis with two ingestion paths (archive upload and public GitHub URL), account-scoped project containers for grouping and tracking repeated analyses, history with metadata that survives artifact purge, one-click manual reruns for GitHub-backed projects, deterministic diffs between any two completed runs within a project, and a billing layer with plan-aware submission guardrails and hosted checkout. Routes are account-scoped with a temporary beta account resolution mechanism.

Open family overviewView dashboard

Current status

Eighteen endpoints are live under /v1/integration-intelligence, covering the full analysis lifecycle, submission preflight, project management, run history, manual reruns, deterministic diffs, and billing. All routes are account-scoped with temporary beta account resolution.

Namespace/v1/integration-intelligence
Endpoint count18 documented routes

Planned capabilities

The scope below is descriptive only. No route should be treated as live until the status changes.

  • Repository archive upload and analysis job creation
  • Public GitHub repository URL ingestion with resolved ref and commit provenance
  • Queued, running, completed, and failed job lifecycle tracking
  • Canonical JSON result retrieval for completed analyses
  • Rich JSON export retrieval with lifecycle, provenance, input, and artifact metadata
  • Derived Markdown report export for human-readable review (paid plan)
  • Derived Mermaid graph export for relationship review (paid plan)
  • Automatic expiry of stored analysis artifacts after the retention window
  • Explicit analysis deletion for privacy-sensitive customer repositories
  • Submission preflight with plan-aware usage checks before upload
  • Account-scoped project containers with slug-based identity
  • Project history with metadata survival after artifact purge
  • Manual rerun from GitHub-backed project context
  • Deterministic diffs between completed runs within a project
  • Plan-enforced billing with hosted checkout and provider webhook handling

Purpose

Integration Intelligence provides a complete repository analysis workflow from submission through comparison, organized around account-scoped projects with run history and plan-aware billing.

  • Pre-check submission eligibility with plan-aware preflight
  • Submit a repository archive or public GitHub URL for asynchronous analysis
  • Track analysis progress through queued, running, completed, and failed states
  • Retrieve canonical JSON results, rich JSON export bundles, Markdown reports, and Mermaid graphs
  • Organize analyses into projects for long-lived tracking
  • View run history per project with metadata that survives artifact purge
  • Rerun GitHub-backed projects with optional ref or profile overrides
  • Compare any two completed runs within a project via deterministic diff

Design rules

  • All endpoints stay under /v1/integration-intelligence/*
  • The /results payload is the canonical findings contract; export.json bundles richer lifecycle and artifact context
  • Archive upload and public GitHub URLs are the two ingestion methods
  • Non-2xx responses use a consistent machine-readable error structure with code and message fields

Account scope and beta authentication

All routes are account-scoped. The current beta implementation resolves a default account automatically when no explicit account is specified, or accepts an x-devtools-account-id header for explicit account targeting. This is a temporary beta mechanism — the account resolution approach may change, but route contracts and response shapes will remain stable.

  • Every analysis, project, and usage record is associated with an account
  • The x-devtools-account-id header is optional; omitting it uses a default account
  • Account isolation ensures that one account cannot access another account's projects or analyses

Ingestion and preflight

  • Accepted archive formats: .zip, .tar.gz, .tgz
  • Max archive size depends on plan: 25 MB for free, 100 MB for paid
  • Max unpacked files: 10,000
  • Ignored patterns include node_modules/, .git/, dist/, build/, coverage/, *.min.js, *.map, and *.lock
  • Remote URL ingestion is limited to public github.com repositories
  • The preflight endpoint pre-checks submission eligibility, plan limits, and archive size before upload

Project model

A project is the long-lived container for repeated analyses of the same repository. Projects are account-scoped and identified by an auto-generated slug derived from the display name.

  • Projects group analyses for history, rerun, and diff workflows
  • Upload-origin and GitHub-origin projects differ in rerun support — only GitHub-backed projects support one-click rerun
  • Project slugs are unique per account
  • A project's latestAnalysisId is updated whenever a new analysis is created under it

Manual rerun rules

  • Reruns are manual only — there is no automatic rerun scheduling
  • Reruns are currently supported for GitHub-backed projects only
  • Each rerun creates a new analysis and consumes quota like a normal submission
  • Optional overrides for ref, stack_hint, and profile are accepted; defaults come from the project record

Diff rules

Diffs are deterministic comparisons of stored analysis results. They do not re-analyze code — they compare the JSON findings from two completed runs.

  • Both analyses must belong to the same project
  • Both analyses must be in completed status
  • Both analyses must still have stored results (not retention-purged)
  • The diff identifies added, removed, and changed items across endpoints, auth, integrations, background jobs, config dependencies, and data models

Retention and history

  • Stored archives, workspaces, and rendered outputs expire based on plan retention (7 days free, longer for paid)
  • DELETE /v1/integration-intelligence/analyses/{analysisId} permanently removes an analysis and its artifacts
  • Running analyses reject deletion with 409 to protect in-flight jobs
  • Project history metadata (status, timestamps, trigger kind) remains visible even after artifacts are purged
  • Diffs stop working once required stored artifacts are purged

Billing and plan enforcement

Submission guardrails enforce plan limits before and during analysis creation. Preflight, archive upload, GitHub ingestion, and rerun all check entitlements.

  • Free plan: 3 analyses per 30-day billing period, 25 MB max archive, JSON export only
  • Paid plan (paid_analysis_pack): 25 analyses per period, 100 MB max archive, JSON + Markdown + Mermaid exports, priority processing
  • The checkout endpoint creates a hosted Paddle checkout session for plan upgrades
  • The billing webhook receives Paddle-signed events and applies plan changes idempotently
  • Routes may return 501 BILLING_NOT_CONFIGURED when the billing adapter is not present in the environment

Endpoint reference

The routes below are documented from the shared platform registry and reflect the current implemented contract for this family. Some routes may be environment-dependent, such as billing when no adapter is configured.

Return a simple liveness and readiness response.

The intentionally boring health endpoint for the Integration Intelligence family, used to verify that the process is reachable and serving requests.

GET /v1/integration-intelligence/health
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Response content typeapplication/json

Response highlights

  • service: stable service identifier
  • status: ok when healthy
  • version: current deployed app version when available

Implementation notes

  • The initial implementation should return a minimal, boring response shape.
  • This endpoint is the first recommended implementation step in the family roadmap.

Create a new analysis job from an uploaded repository archive.

This endpoint starts the full analysis lifecycle: archive accepted, job created, work queued, worker processes it asynchronously, and downstream retrieval endpoints become available.

POST /v1/integration-intelligence/analyses
Handler statusImplemented
Intended success202
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Request content typemultipart/form-data

Request fields

  • file (required): Repository archive file.
  • stack_hint (optional): Optional hint such as node-express.
  • profile (optional): Optional analysis profile name.
  • ignore_patterns (optional): Optional repeated field or JSON string for extra ignore patterns.

Response highlights

  • analysis_id: unique analysis job ID
  • status: queued on initial acceptance
  • created_at: UTC timestamp
  • repository.name: original uploaded archive name or normalized repository name

Implementation notes

  • Return 202 Accepted because analysis is asynchronous.
  • The API layer should create the job record and enqueue work, not perform the analysis directly.
  • Requests should be rejected when the file is missing, malformed, unsupported, too large, or unpacking fails.

Create a new analysis job from a public GitHub repository URL.

This endpoint resolves a public github.com repository URL, optionally pins a requested ref to a commit SHA, downloads the source archive server-side, and then starts the same asynchronous analysis lifecycle used for uploaded archives.

POST /v1/integration-intelligence/analyses/github
Handler statusImplemented
Intended success202
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Request content typeapplication/json

Request fields

  • repository_url (required): Public github.com repository URL. Repository root URLs and /tree/{ref} URLs are supported.
  • ref (optional): Optional branch, tag, or commit to analyze. Overrides the default branch unless the URL already includes /tree/{ref}.
  • stack_hint (optional): Optional hint such as node-express or python-flask.
  • profile (optional): Optional analysis profile name.
  • ignore_patterns (optional): Optional JSON array of extra ignore patterns.

Response highlights

  • analysis_id: unique analysis job ID
  • status: queued on initial acceptance
  • created_at: UTC timestamp
  • repository.name: normalized GitHub repository name

Implementation notes

  • Only public github.com repositories are supported in the first pass.
  • The API does not accept arbitrary remote URLs yet.
  • GitHub repository metadata and the resolved commit SHA are persisted with the analysis job.

Poll analysis job status as a lifecycle and provenance manifest.

This polling endpoint returns whether an analysis is queued, running, completed, or failed, plus lifecycle metadata, source provenance, normalized submission inputs, export readiness, and compact summary counts when findings are available, without returning the full findings payload.

GET /v1/integration-intelligence/analyses/{analysisId}
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Response content typeapplication/json

Path parameters

  • analysisId: UUID of the analysis job.

Response highlights

  • status: queued, running, completed, or failed
  • created_at, started_at, completed_at, duration_ms, and expires_at lifecycle fields
  • source provenance and normalized submission-input metadata
  • artifact readiness with direct hrefs for /results, /export.json, /report.md, and /graph.mmd
  • compact repository and findings summary metadata without embedding the full findings arrays
  • failure.code and failure.message when the job has failed

Implementation notes

  • This endpoint is for polling and manifest/provenance review and should not return the full findings payload.
  • Invalid IDs should produce INVALID_REQUEST and unknown IDs should produce ANALYSIS_NOT_FOUND.

Permanently delete an analysis record and its stored artifacts.

This privacy-focused endpoint removes the stored archive, extracted workspace, persisted JSON result, Markdown report, Mermaid graph, and the parent analysis row when the job is no longer running.

DELETE /v1/integration-intelligence/analyses/{analysisId}
Handler statusImplemented
Intended success204
AuthenticationAccount-scoped. Default account resolved automatically in beta.

Path parameters

  • analysisId: UUID of the analysis job.

Response highlights

  • 204 No Content when deletion succeeds
  • 409 INVALID_REQUEST if the analysis is still running
  • Queued jobs are removed from the queue before the row and artifacts are deleted

Implementation notes

  • Deletion is irreversible and intended for privacy-sensitive repository uploads.
  • Expired analyses are also purged automatically after the retention window.

Return the canonical JSON result set for a completed analysis.

This is the primary retrieval endpoint in the MVP because JSON remains the source of truth for all downstream exports.

GET /v1/integration-intelligence/analyses/{analysisId}/results
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Response content typeapplication/json

Path parameters

  • analysisId: UUID of the analysis job.

Response highlights

  • Completed analysis lifecycle metadata
  • Repository detection metadata
  • Canonical findings for endpoints, integrations, jobs, configs, data models, risks, unknowns, and summary

Implementation notes

  • Only completed analyses should return results.
  • If the analysis exists but is not complete yet, the intended contract is 409 INVALID_REQUEST.
  • Unsupported stacks should still be allowed to complete with sparse findings plus explanatory unknowns.

Return a richer JSON export bundle for any stored analysis.

This export-oriented endpoint bundles lifecycle metadata, source provenance, normalized input details, the canonical result when available, and derived Markdown and Mermaid artifacts for completed analyses.

GET /v1/integration-intelligence/analyses/{analysisId}/export.json
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Response content typeapplication/json

Path parameters

  • analysisId: UUID of the analysis job.

Response highlights

  • Analysis lifecycle fields including started_at and expires_at
  • Source provenance for uploads and public GitHub ingestion
  • Submission inputs such as stack_hint, profile, ignore_patterns, and archive metadata
  • Canonical result plus Markdown and Mermaid artifacts when the analysis has completed

Implementation notes

  • This endpoint is intended for export, download, and richer debug workflows.
  • The /results payload remains the canonical findings contract for downstream consumers.

Return a human-readable Markdown report for a completed analysis.

This is a derived export built from the analysis export bundle. It is intended to be a fuller downloadable report with lifecycle metadata, provenance, submission inputs, detailed findings, and the Mermaid service graph.

GET /v1/integration-intelligence/analyses/{analysisId}/report.md
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Response content typetext/markdown; charset=utf-8

Path parameters

  • analysisId: UUID of the analysis job.

Response highlights

  • Analysis lifecycle, provenance, and submission-input sections rendered as Markdown
  • Detailed endpoint, auth, integration, job, config, model, risk, and unknown sections
  • Embedded Mermaid service graph plus graph data summary

Implementation notes

  • Markdown is a derived export, never the source of truth.
  • If the report is requested before completion, the intended contract is 409 INVALID_REQUEST.
  • Markdown export requires a paid plan. Free-tier accounts receive 403 EXPORT_NOT_ALLOWED.

Return a Mermaid graph export for a completed analysis.

This derived export renders the current canonical graph data as a richer merged Mermaid topology so reviewers can inspect service and integration relationships, provenance hints, and finding coverage without reading raw JSON.

GET /v1/integration-intelligence/analyses/{analysisId}/graph.mmd
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Response content typetext/plain; charset=utf-8

Path parameters

  • analysisId: UUID of the analysis job.

Response highlights

  • Merged service and integration topology rendered from canonical graph nodes and edges
  • Header comments with analysis metadata, source provenance, and finding counts
  • Certainty styling for inferred or uncertain nodes and links

Implementation notes

  • Mermaid is a derived export, never the source of truth.
  • If the graph is requested before completion, the intended contract is 409 INVALID_REQUEST.
  • Mermaid export requires a paid plan. Free-tier accounts receive 403 EXPORT_NOT_ALLOWED.

Pre-check submission eligibility before upload.

Returns whether the current account is allowed to submit a new analysis given plan limits and optional archive size, along with current usage metrics and plan details.

POST /v1/integration-intelligence/analyses/preflight
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Request content typeapplication/json
Response content typeapplication/json

Request fields

  • archive_size_bytes (optional): Size in bytes of the archive to validate. Defaults to 0 if omitted.

Response highlights

  • allowed: whether submission would be accepted
  • reason_code: PLAN_LIMIT_REACHED or REPO_TOO_LARGE when blocked
  • suggested_plan_code: recommended upgrade target when blocked
  • usage: analyses_used, analyses_remaining, analyses_limit, billing_period_start, billing_period_end
  • plan: code, max_archive_bytes, retention_days, allowed_exports, priority_processing

Implementation notes

  • This endpoint should be called before upload to avoid rejected submissions.
  • The response includes complete plan and usage information for client-side display.

Create a project container for repeated analyses.

Creates an account-scoped project with an auto-generated slug derived from the display name. Projects group analyses for history, rerun, and diff workflows.

POST /v1/integration-intelligence/projects
Handler statusImplemented
Intended success201
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Request content typeapplication/json
Response content typeapplication/json

Request fields

  • display_name (required): Project name. 1–200 characters, trimmed.
  • description (optional): Optional project description. Max 1000 characters.
  • repository_name (optional): Optional repository identifier.
  • source_type (optional): Project source type: github-public, upload, or unknown. Defaults to unknown.
  • source_url (optional): URL to the source repository.
  • source_owner (optional): Repository owner or organization name.
  • source_repo (optional): Repository name without owner prefix.
  • source_ref (optional): Default git branch or tag reference.
  • stack_hint (optional): Default technology stack hint for analyses.
  • profile (optional): Default analysis profile name.

Response highlights

  • id: unique project UUID
  • slug: URL-safe identifier derived from display_name
  • displayName, description, and source metadata fields
  • latestAnalysisId: null on creation
  • createdAt, updatedAt: UTC timestamps

Implementation notes

  • Slug is unique per account. Returns 409 if a project with the same slug already exists.
  • Source metadata enables rerun support for GitHub-backed projects.

List projects for the current account.

Returns all projects belonging to the current account, ordered by most recent first. Each project record includes source metadata and the latest analysis reference if present.

GET /v1/integration-intelligence/projects
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Response content typeapplication/json

Response highlights

  • Array of project records with id, slug, displayName, and source metadata
  • latestAnalysisId present when analyses have been run under the project
  • Up to 100 projects returned per request

Implementation notes

  • Results are scoped to the requesting account.
  • This is the entry point for project-aware dashboard views.

Fetch a single project record by ID.

Returns the full project record including source metadata, default analysis settings, and the latest analysis reference.

GET /v1/integration-intelligence/projects/{projectId}
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Response content typeapplication/json

Path parameters

  • projectId: UUID of the project.

Response highlights

  • Full project record with id, slug, displayName, description, and all source metadata
  • latestAnalysisId when analyses exist
  • createdAt, updatedAt timestamps

Implementation notes

  • Returns 404 PROJECT_NOT_FOUND if the project does not exist.
  • Returns 403 PROJECT_ACCOUNT_MISMATCH if the project belongs to a different account.

Return project metadata plus run history.

Returns the project record together with a chronological list of all analysis runs associated with the project, including lifecycle metadata that remains visible even after artifact purge.

GET /v1/integration-intelligence/projects/{projectId}/history
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Response content typeapplication/json

Path parameters

  • projectId: UUID of the project.

Response highlights

  • project: full project record
  • history: array of run entries with analysisId, projectRunNumber, status, timestamps
  • Each history entry includes sourceType, sourceUrl, sourceRef, sourceCommitSha
  • triggerKind: manual_upload, manual_github, or manual_rerun
  • rerunOfAnalysisId: set when the run was triggered as a rerun
  • artifactsAvailable: whether results can still be fetched
  • artifactsPurgedAt: timestamp when artifacts were retention-purged, if applicable

Implementation notes

  • History metadata survives artifact purge — run entries remain visible with artifactsAvailable set to false.
  • Up to 100 history entries returned per request.

Create a new analysis run from an existing project.

Triggers a new analysis using the project's stored GitHub source, with optional overrides for ref, stack hint, and profile. The rerun consumes quota like a normal submission and creates a new analysis linked to the project.

POST /v1/integration-intelligence/projects/{projectId}/rerun
Handler statusImplemented
Intended success202
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Request content typeapplication/json
Response content typeapplication/json

Path parameters

  • projectId: UUID of the project.

Request fields

  • ref (optional): Git reference override (branch or tag). Falls back to the project's default if omitted.
  • stack_hint (optional): Stack hint override. Falls back to the project's default if omitted.
  • profile (optional): Analysis profile override. Falls back to the project's default if omitted.

Response highlights

  • analysis_id: unique ID of the new analysis
  • status: queued on initial acceptance
  • created_at: UTC timestamp

Implementation notes

  • Only supported for projects with source_type github-public and a stored source_url. Returns 409 PROJECT_RERUN_NOT_SUPPORTED otherwise.
  • Each rerun consumes one analysis from the account's monthly quota. Returns 429 PLAN_LIMIT_REACHED if the quota is exhausted.
  • The new analysis records triggerKind as manual_rerun and links back to the previous latest analysis via rerunOfAnalysisId.

Compare two completed runs within a project.

Returns a deterministic diff between two completed analyses in the same project, identifying added, removed, and changed findings across all categories without re-analyzing code.

GET /v1/integration-intelligence/projects/{projectId}/diff
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Response content typeapplication/json

Path parameters

  • projectId: UUID of the project.

Query parameters

  • from_analysis_id: UUID of the baseline analysis for comparison.
  • to_analysis_id: UUID of the target analysis for comparison.

Response highlights

  • summary: changesDetected flag, categoriesChanged count, and per-category change counts
  • Per-category diff sections for endpoints, auth, integrations, backgroundJobs, configDependencies, and dataModels
  • Each category lists added, removed, and changed item identifiers
  • Delta counts for total endpoints, integrations, background jobs, config dependencies, data models, risks, and unknowns

Implementation notes

  • Both from_analysis_id and to_analysis_id are required query parameters. Returns 400 INVALID_REQUEST if either is missing.
  • Both analyses must belong to the specified project. Returns 409 ANALYSIS_PROJECT_MISMATCH otherwise.
  • Both analyses must be in completed status. Returns 409 PROJECT_DIFF_REQUIRES_COMPLETED_RUNS otherwise.
  • Both analyses must still have stored results. Returns 410 ANALYSIS_ARTIFACTS_PURGED if retention has removed either result set.

Create a hosted checkout session for plan upgrade.

Creates a Paddle-hosted checkout session that redirects the user to complete payment for a plan upgrade. Returns a checkout URL and transaction reference.

POST /v1/integration-intelligence/billing/checkout
Handler statusImplemented
Intended success200
AuthenticationAccount-scoped. Default account resolved automatically in beta.
Request content typeapplication/json
Response content typeapplication/json

Request fields

  • target_plan_code (required): Plan to upgrade to. Currently accepts paid_analysis_pack.
  • success_url (required): Full URL to redirect to after successful checkout.
  • cancel_url (required): Full URL to redirect to if the user cancels checkout.

Response highlights

  • checkout_url: URL to redirect the user to for payment
  • transaction_id: provider session reference for tracking

Implementation notes

  • Returns 501 BILLING_NOT_CONFIGURED when the billing adapter is not present in the environment.
  • After successful payment, the billing webhook handles plan activation.

Receive provider-signed billing events from Paddle.Provider callback

Provider callback endpoint that receives Paddle-signed webhook events for subscription lifecycle changes. Verifies the signature, ingests the event idempotently, and applies plan changes when applicable. This endpoint is not intended for normal customer-triggered requests.

POST /v1/integration-intelligence/billing/webhook
Handler statusImplemented
Intended success200
Response content typeapplication/json

Headers

  • Paddle-Signature: Webhook signature from Paddle for request verification. Required.

Response highlights

  • outcome: processed when the event was handled, or duplicate when the event was already ingested

Implementation notes

  • This is a provider callback endpoint, not a normal customer API route.
  • Returns 400 if the Paddle-Signature header is missing or the signature is invalid.
  • Duplicate events are handled idempotently and return outcome: duplicate.
  • Returns 501 BILLING_NOT_CONFIGURED when the billing adapter is not present in the environment.
  • Handles subscription.created, subscription.updated, subscription.canceled, and other Paddle lifecycle events.

Activation path

When implementation moves beyond placeholders, keep the namespace, docs page, and dashboard label aligned. Replace placeholder handlers in the corresponding API module rather than redesigning the platform surface.