openapi: 3.0.0
info:
title: Symbiont Tool Review API
description: AI-driven tool review and signing workflow API
version: 1.0.0
contact:
name: Symbiont Platform Team
email: api-support@symbiont.platform
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.symbiont.platform/v1/tool-review
description: Production server
- url: https://staging-api.symbiont.platform/v1/tool-review
description: Staging server
security:
- BearerAuth: []
paths:
/sessions:
post:
summary: Submit tool for review
description: Submit an MCP tool for security analysis and review
operationId: submitTool
tags:
- Review Sessions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ToolSubmission'
responses:
'201':
description: Tool submitted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SubmissionResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
get:
summary: List review sessions
description: Get a paginated list of review sessions
operationId: listSessions
tags:
- Review Sessions
parameters:
- name: status
in: query
description: Filter by review status
schema:
type: string
enum: [pending_review, under_review, awaiting_human_review, approved, rejected, signed, signing_failed]
- name: page
in: query
description: Page number
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
description: Items per page
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
'200':
description: List of review sessions
content:
application/json:
schema:
$ref: '#/components/schemas/SessionList'
/sessions/{reviewId}:
get:
summary: Get review session details
description: Get detailed information about a specific review session
operationId: getSession
tags:
- Review Sessions
parameters:
- name: reviewId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Review session details
content:
application/json:
schema:
$ref: '#/components/schemas/ReviewSession'
'404':
$ref: '#/components/responses/NotFound'
/analysis/{analysisId}:
get:
summary: Get security analysis details
description: Get detailed security analysis results
operationId: getAnalysis
tags:
- Security Analysis
parameters:
- name: analysisId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Security analysis details
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityAnalysis'
/review/queue:
get:
summary: Get human review queue
description: Get pending items requiring human review
operationId: getReviewQueue
tags:
- Human Review
responses:
'200':
description: Review queue items
content:
application/json:
schema:
$ref: '#/components/schemas/ReviewQueue'
/review/{reviewId}/decision:
post:
summary: Submit human review decision
description: Submit approval or rejection decision for a tool
operationId: submitDecision
tags:
- Human Review
parameters:
- name: reviewId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HumanDecision'
responses:
'200':
description: Decision submitted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DecisionResponse'
/signing/{reviewId}:
get:
summary: Get signing status
description: Get the signing status and signature information
operationId: getSigningStatus
tags:
- Tool Signing
parameters:
- name: reviewId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Signing status
content:
application/json:
schema:
$ref: '#/components/schemas/SigningStatus'
/signing/{reviewId}/download:
get:
summary: Download signed tool
description: Download the signed tool with signature
operationId: downloadSignedTool
tags:
- Tool Signing
parameters:
- name: reviewId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Signed tool
content:
application/json:
schema:
$ref: '#/components/schemas/SignedTool'
/stats:
get:
summary: Get workflow statistics
description: Get overall workflow statistics and metrics
operationId: getStats
tags:
- Statistics
responses:
'200':
description: Workflow statistics
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowStats'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
ToolSubmission:
type: object
required:
- tool
- submitted_by
properties:
tool:
$ref: '#/components/schemas/McpTool'
submitted_by:
type: string
format: email
priority:
type: string
enum: [low, normal, high, urgent]
default: normal
McpTool:
type: object
required:
- name
- description
- schema
- provider
properties:
name:
type: string
minLength: 1
maxLength: 100
description:
type: string
minLength: 1
maxLength: 500
schema:
type: object
provider:
$ref: '#/components/schemas/ToolProvider'
ToolProvider:
type: object
required:
- name
- public_key_url
properties:
name:
type: string
public_key_url:
type: string
format: uri
SubmissionResponse:
type: object
properties:
review_id:
type: string
format: uuid
status:
type: string
enum: [pending_review]
submitted_at:
type: string
format: date-time
estimated_completion:
type: string
format: date-time
ReviewSession:
type: object
properties:
review_id:
type: string
format: uuid
tool:
$ref: '#/components/schemas/McpTool'
state:
$ref: '#/components/schemas/ReviewState'
security_analysis:
$ref: '#/components/schemas/SecurityAnalysisSummary'
audit_trail:
type: array
items:
$ref: '#/components/schemas/AuditEvent'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
ReviewState:
oneOf:
- $ref: '#/components/schemas/PendingReviewState'
- $ref: '#/components/schemas/UnderReviewState'
- $ref: '#/components/schemas/AwaitingHumanReviewState'
- $ref: '#/components/schemas/ApprovedState'
- $ref: '#/components/schemas/RejectedState'
- $ref: '#/components/schemas/SignedState'
PendingReviewState:
type: object
properties:
type:
type: string
enum: [pending_review]
submitted_at:
type: string
format: date-time
submitted_by:
type: string
UnderReviewState:
type: object
properties:
type:
type: string
enum: [under_review]
started_at:
type: string
format: date-time
analyzer_id:
type: string
analysis_id:
type: string
format: uuid
AwaitingHumanReviewState:
type: object
properties:
type:
type: string
enum: [awaiting_human_review]
analysis_id:
type: string
format: uuid
analysis_completed_at:
type: string
format: date-time
critical_findings:
type: array
items:
$ref: '#/components/schemas/SecurityFinding'
risk_score:
type: number
minimum: 0
maximum: 1
ai_recommendation:
$ref: '#/components/schemas/ReviewRecommendation'
ApprovedState:
type: object
properties:
type:
type: string
enum: [approved]
approved_by:
type: string
approved_at:
type: string
format: date-time
approval_notes:
type: string
RejectedState:
type: object
properties:
type:
type: string
enum: [rejected]
rejected_by:
type: string
rejected_at:
type: string
format: date-time
rejection_reason:
type: string
SignedState:
type: object
properties:
type:
type: string
enum: [signed]
signature_info:
$ref: '#/components/schemas/SignatureInfo'
signed_at:
type: string
format: date-time
signed_by:
type: string
SecurityFinding:
type: object
properties:
finding_id:
type: string
severity:
type: string
enum: [low, medium, high, critical]
category:
type: string
enum: [schema_injection, privilege_escalation, data_exfiltration, malicious_code, suspicious_parameters, unvalidated_input, insecure_defaults, other]
title:
type: string
description:
type: string
location:
type: string
confidence:
type: number
minimum: 0
maximum: 1
remediation_suggestion:
type: string
cve_references:
type: array
items:
type: string
ReviewRecommendation:
oneOf:
- type: object
properties:
type:
type: string
enum: [approve]
confidence:
type: number
reasoning:
type: string
- type: object
properties:
type:
type: string
enum: [reject]
confidence:
type: number
reasoning:
type: string
- type: object
properties:
type:
type: string
enum: [requires_human_judgment]
reasoning:
type: string
SecurityAnalysis:
type: object
properties:
analysis_id:
type: string
format: uuid
tool_id:
type: string
analyzed_at:
type: string
format: date-time
analyzer_version:
type: string
risk_score:
type: number
minimum: 0
maximum: 1
findings:
type: array
items:
$ref: '#/components/schemas/SecurityFinding'
recommendations:
type: array
items:
type: string
confidence_score:
type: number
minimum: 0
maximum: 1
analysis_metadata:
$ref: '#/components/schemas/AnalysisMetadata'
SecurityAnalysisSummary:
type: object
properties:
analysis_id:
type: string
format: uuid
risk_score:
type: number
confidence_score:
type: number
findings_count:
type: integer
processing_time_ms:
type: integer
AnalysisMetadata:
type: object
properties:
processing_time_ms:
type: integer
rag_queries_performed:
type: integer
knowledge_sources_consulted:
type: array
items:
type: string
patterns_matched:
type: array
items:
type: string
false_positive_likelihood:
type: number
HumanDecision:
type: object
required:
- decision
- reasoning
- operator_id
properties:
decision:
type: string
enum: [approve, reject, request_reanalysis, escalate_to_senior]
reasoning:
type: string
minLength: 10
operator_id:
type: string
time_spent_seconds:
type: integer
minimum: 0
additional_notes:
type: string
DecisionResponse:
type: object
properties:
decision_id:
type: string
review_id:
type: string
format: uuid
status:
type: string
next_action:
type: string
decided_at:
type: string
format: date-time
SigningStatus:
type: object
properties:
review_id:
type: string
format: uuid
signing_status:
type: string
enum: [pending, in_progress, completed, failed]
signature_info:
$ref: '#/components/schemas/SignatureInfo'
signed_schema:
type: object
SignatureInfo:
type: object
properties:
signature:
type: string
algorithm:
type: string
public_key_url:
type: string
format: uri
signed_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
SignedTool:
type: object
properties:
tool:
allOf:
- $ref: '#/components/schemas/McpTool'
- type: object
properties:
verification_status:
type: string
enum: [signed]
signature_info:
$ref: '#/components/schemas/SignatureInfo'
SessionList:
type: object
properties:
sessions:
type: array
items:
$ref: '#/components/schemas/SessionSummary'
pagination:
$ref: '#/components/schemas/Pagination'
SessionSummary:
type: object
properties:
review_id:
type: string
format: uuid
tool_name:
type: string
status:
type: string
risk_score:
type: number
submitted_at:
type: string
format: date-time
submitted_by:
type: string
ReviewQueue:
type: object
properties:
pending_reviews:
type: array
items:
$ref: '#/components/schemas/QueueItem'
queue_stats:
$ref: '#/components/schemas/QueueStats'
QueueItem:
type: object
properties:
review_id:
type: string
format: uuid
tool_name:
type: string
provider:
type: string
risk_score:
type: number
critical_findings_count:
type: integer
high_findings_count:
type: integer
ai_recommendation:
type: string
priority_score:
type: number
submitted_at:
type: string
format: date-time
time_in_queue:
type: string
format: duration
QueueStats:
type: object
properties:
total_pending:
type: integer
high_priority:
type: integer
avg_wait_time:
type: string
format: duration
WorkflowStats:
type: object
properties:
overall:
$ref: '#/components/schemas/OverallStats'
current_queue:
$ref: '#/components/schemas/CurrentQueueStats'
top_security_categories:
type: array
items:
$ref: '#/components/schemas/CategoryCount'
time_period:
$ref: '#/components/schemas/TimePeriod'
OverallStats:
type: object
properties:
total_reviews:
type: integer
approved_tools:
type: integer
rejected_tools:
type: integer
signed_tools:
type: integer
avg_analysis_time_ms:
type: integer
avg_human_review_time_ms:
type: integer
auto_approval_rate:
type: number
false_positive_rate:
type: number
CurrentQueueStats:
type: object
properties:
pending_analysis:
type: integer
awaiting_human_review:
type: integer
pending_signing:
type: integer
CategoryCount:
type: object
properties:
category:
type: string
count:
type: integer
TimePeriod:
type: object
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
Pagination:
type: object
properties:
page:
type: integer
limit:
type: integer
total:
type: integer
total_pages:
type: integer
AuditEvent:
type: object
properties:
event_type:
type: string
timestamp:
type: string
format: date-time
actor:
type: string
details:
type: object
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
request_id:
type: string
timestamp:
type: string
format: date-time
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-RateLimit-Limit:
schema:
type: integer
X-RateLimit-Remaining:
schema:
type: integer
X-RateLimit-Reset:
schema:
type: integer
tags:
- name: Review Sessions
description: Tool review session management
- name: Security Analysis
description: Security analysis operations
- name: Human Review
description: Human review workflow
- name: Tool Signing
description: Tool signing operations
- name: Statistics
description: Workflow statistics and monitoring