818 lines
23 KiB
YAML
818 lines
23 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: PyraFiles API
|
|
version: 1.0.0
|
|
description: |
|
|
API specification for the PyraFiles application.
|
|
PyraFiles allows users to register, authenticate, manage namespaces,
|
|
generate JWT tokens for agents, and manage media files within namespaces.
|
|
|
|
servers:
|
|
- url: http://127.0.0.1:{port}
|
|
description: Local development server
|
|
variables:
|
|
port:
|
|
default: '6544'
|
|
- url: https://files.example.com
|
|
description: Production server
|
|
|
|
paths:
|
|
/:
|
|
get:
|
|
summary: Home Page
|
|
description: Displays the home page with public namespaces and user namespaces.
|
|
responses:
|
|
'200':
|
|
description: Successful response
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
|
|
/auth/login:
|
|
get:
|
|
summary: Display Login Page
|
|
description: Renders the login page where users can enter their email.
|
|
responses:
|
|
'200':
|
|
description: Login page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
post:
|
|
summary: Process Login
|
|
description: Sends a verification code to the user's email.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
required:
|
|
- email
|
|
responses:
|
|
'302':
|
|
description: Redirects to the verification page
|
|
headers:
|
|
Location:
|
|
description: URL of the verification page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., email missing)
|
|
|
|
/auth/verify:
|
|
get:
|
|
summary: Display Verification Page
|
|
description: Renders the verification page where users can enter their code.
|
|
responses:
|
|
'200':
|
|
description: Verification page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
post:
|
|
summary: Verify User
|
|
description: Verifies the user's code and logs them in.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
required:
|
|
- code
|
|
responses:
|
|
'302':
|
|
description: Redirects to the home page upon successful verification
|
|
headers:
|
|
Location:
|
|
description: URL of the home page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., invalid code)
|
|
|
|
/auth/logout:
|
|
post:
|
|
summary: Logout User
|
|
description: Logs out the current user.
|
|
security:
|
|
- sessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
csrf_token:
|
|
type: string
|
|
responses:
|
|
'302':
|
|
description: Redirects to the home page
|
|
headers:
|
|
Location:
|
|
description: URL of the home page
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Unauthorized (user not logged in)
|
|
|
|
/auth/profile:
|
|
get:
|
|
summary: Display User Profile
|
|
description: Shows the user's profile, including owned namespaces.
|
|
security:
|
|
- sessionAuth: []
|
|
responses:
|
|
'200':
|
|
description: Profile page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Unauthorized (user not logged in)
|
|
post:
|
|
summary: Update User Profile
|
|
description: Updates the user's profile settings.
|
|
security:
|
|
- sessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
enable_gravatar:
|
|
type: string
|
|
enum: ['on']
|
|
new_username:
|
|
type: string
|
|
encoding:
|
|
enable_gravatar:
|
|
contentType: text/plain
|
|
new_username:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the profile page
|
|
headers:
|
|
Location:
|
|
description: URL of the profile page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., username already in use)
|
|
'403':
|
|
description: Unauthorized (user not logged in)
|
|
|
|
/namespace/create:
|
|
get:
|
|
summary: Display Namespace Creation Page
|
|
description: Renders the form to create a new namespace.
|
|
security:
|
|
- sessionAuth: []
|
|
responses:
|
|
'200':
|
|
description: Namespace creation page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Unauthorized (user not logged in)
|
|
post:
|
|
summary: Create Namespace
|
|
description: Processes the namespace creation form.
|
|
security:
|
|
- sessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
is_public:
|
|
type: string
|
|
enum: ['on']
|
|
encoding:
|
|
name:
|
|
contentType: text/plain
|
|
is_public:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., namespace name already exists)
|
|
'403':
|
|
description: Unauthorized (user not logged in)
|
|
|
|
/namespace/{namespace_short_id}/manage:
|
|
get:
|
|
summary: Manage Namespace (Owners Only)
|
|
description: Displays the namespace management page. **Requires 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
responses:
|
|
'200':
|
|
description: Namespace management page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace not found
|
|
|
|
/namespace/{namespace_short_id}/update:
|
|
post:
|
|
summary: Update Namespace (Owners Only)
|
|
description: Updates namespace properties. **Requires 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
is_public:
|
|
type: string
|
|
enum: ['on']
|
|
description: 'Checkbox value. Present if checked.'
|
|
encoding:
|
|
is_public:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace not found
|
|
|
|
/namespace/{namespace_short_id}/invite:
|
|
post:
|
|
summary: Invite User to Namespace (Owners Only)
|
|
description: Invites a user to the namespace with a specified role. **Requires 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
role:
|
|
type: string
|
|
enum: ['owner', 'editor', 'reader']
|
|
required:
|
|
- email
|
|
- role
|
|
encoding:
|
|
email:
|
|
contentType: text/plain
|
|
role:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., invalid role)
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace not found
|
|
|
|
/namespace/{namespace_short_id}/remove_user:
|
|
post:
|
|
summary: Remove User from Namespace (Owners Only)
|
|
description: Removes a user from the namespace. **Requires 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
required:
|
|
- user_id
|
|
encoding:
|
|
user_id:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., cannot remove self)
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace or user not found
|
|
|
|
/namespace/{namespace_short_id}/change_member_role:
|
|
post:
|
|
summary: Change Member Role in Namespace (Owners Only)
|
|
description: Changes a member's role in the namespace. **Requires 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
role:
|
|
type: string
|
|
enum: ['owner', 'editor', 'reader']
|
|
required:
|
|
- user_id
|
|
- role
|
|
encoding:
|
|
user_id:
|
|
contentType: text/plain
|
|
role:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., cannot change own role)
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace or user not found
|
|
|
|
/namespace/{namespace_short_id}/generate_agent_jwt:
|
|
post:
|
|
summary: Generate Agent JWT (Owners Only)
|
|
description: Generates a JWT token for an agent. **Requires 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
agent_name:
|
|
type: string
|
|
agent_role:
|
|
type: string
|
|
enum: ['owner', 'editor', 'reader']
|
|
required:
|
|
- agent_name
|
|
- agent_role
|
|
encoding:
|
|
agent_name:
|
|
contentType: text/plain
|
|
agent_role:
|
|
contentType: text/plain
|
|
responses:
|
|
'200':
|
|
description: Agent JWT generated and displayed
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., agent name missing)
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace not found
|
|
|
|
/namespace/{namespace_short_id}/revoke_agent:
|
|
post:
|
|
summary: Revoke Agent (Owners Only)
|
|
description: Revokes an agent's access by invalidating their JWT. **Requires 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
agent_id:
|
|
type: string
|
|
required:
|
|
- agent_id
|
|
encoding:
|
|
agent_id:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., agent ID missing)
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace or agent not found
|
|
|
|
/namespace/{namespace_short_id}/media/upload:
|
|
get:
|
|
summary: Display Media Upload Page (Editors and Owners)
|
|
description: Renders the media upload form. **Requires 'editor' or 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Media upload page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden (insufficient permissions)
|
|
post:
|
|
summary: Upload Media (Editors and Owners)
|
|
description: Uploads a media file to the namespace. **Requires 'editor' or 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
media_file:
|
|
type: string
|
|
format: binary
|
|
title:
|
|
type: string
|
|
is_public:
|
|
type: string
|
|
enum: ['on']
|
|
required:
|
|
- media_file
|
|
responses:
|
|
'302':
|
|
description: Redirects to the media details page
|
|
headers:
|
|
Location:
|
|
description: URL of the media details page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., file missing)
|
|
'403':
|
|
description: Forbidden (insufficient permissions)
|
|
'404':
|
|
description: Namespace not found
|
|
|
|
/namespace/{namespace_short_id}/media/list:
|
|
get:
|
|
summary: List Media in Namespace
|
|
description: Lists all media files in the namespace.
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
- {} # Allow public access if namespace is public
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Media list page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden (insufficient permissions)
|
|
'404':
|
|
description: Namespace not found
|
|
|
|
/namespace/{namespace_short_id}/media/{media_short_id}/details:
|
|
get:
|
|
summary: View Media Details
|
|
description: Displays the details of a media file.
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
- {} # Allow public access if media is public
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- in: path
|
|
name: media_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Media details page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden (insufficient permissions)
|
|
'404':
|
|
description: Media or namespace not found
|
|
|
|
/namespace/{namespace_short_id}/media/{media_short_id}/edit:
|
|
get:
|
|
summary: Display Media Edit Page (Editors and Owners)
|
|
description: Renders the media edit form. **Requires 'editor' or 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- in: path
|
|
name: media_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Media edit page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden (insufficient permissions)
|
|
'404':
|
|
description: Media or namespace not found
|
|
post:
|
|
summary: Edit Media (Editors and Owners)
|
|
description: Updates the media file or metadata. **Requires 'editor' or 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- in: path
|
|
name: media_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
title:
|
|
type: string
|
|
media_file:
|
|
type: string
|
|
format: binary
|
|
is_public:
|
|
type: string
|
|
enum: ['on']
|
|
responses:
|
|
'302':
|
|
description: Redirects to the media details page
|
|
headers:
|
|
Location:
|
|
description: URL of the media details page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., invalid data)
|
|
'403':
|
|
description: Forbidden (insufficient permissions)
|
|
'404':
|
|
description: Media or namespace not found
|
|
|
|
/namespace/{namespace_short_id}/media/{media_short_id}/delete:
|
|
post:
|
|
summary: Delete Media (Editors and Owners)
|
|
description: Deletes the specified media file. **Requires 'editor' or 'owner' role.**
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- in: path
|
|
name: media_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
csrf_token:
|
|
type: string
|
|
responses:
|
|
'302':
|
|
description: Redirects to the media list page
|
|
headers:
|
|
Location:
|
|
description: URL of the media list page
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden (insufficient permissions)
|
|
'404':
|
|
description: Media or namespace not found
|
|
|
|
/namespace/{namespace_short_id}/media/{media_short_id}:
|
|
get:
|
|
summary: View or Download Media
|
|
description: Serves the media file for viewing or downloading.
|
|
security:
|
|
- sessionAuth: []
|
|
- agentAuth: []
|
|
- {} # Allow public access if media is public
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- in: path
|
|
name: media_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- in: query
|
|
name: download
|
|
schema:
|
|
type: boolean
|
|
description: Set to true to download the file
|
|
responses:
|
|
'200':
|
|
description: Media file served
|
|
content:
|
|
'*/*':
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'403':
|
|
description: Forbidden (insufficient permissions)
|
|
'404':
|
|
description: Media or namespace not found
|
|
|
|
components:
|
|
securitySchemes:
|
|
sessionAuth:
|
|
type: apiKey
|
|
in: cookie
|
|
name: session
|
|
description: Session cookie for authenticated users
|
|
agentAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: JWT authentication for agents
|