openapi: 3.0.0
info:
  title: SourceForge Allura API
  description: >-
    The SourceForge REST API provides programmatic access to project management,
    wikis, issue trackers, discussions, blogs, and administrative functions. All
    endpoints are prefixed with /rest/ and follow the project tool path pattern.
    Supports OAuth 2.0 and OAuth 1.0 authentication.
  version: v1
  contact:
    name: SourceForge Support
    url: https://sourceforge.net/p/forge/documentation/API/
  license:
    name: Apache License 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://sourceforge.net
    description: SourceForge REST API
tags:
  - name: Projects
    description: Project creation, retrieval, and permission management
  - name: Wikis
    description: Project wiki page management
  - name: Tracker
    description: Issue and ticket tracking
  - name: Discussion
    description: Forum and discussion thread management
  - name: Blog
    description: Project blog post management
  - name: Admin
    description: Administrative operations including exports, tool installation, and webhooks
  - name: Users
    description: User profile and authentication
paths:
  /rest/p/{project}:
    get:
      operationId: getProject
      summary: Get Project
      description: Retrieve details for a specific SourceForge project.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /rest/p/add_project:
    post:
      operationId: createProject
      summary: Create Project
      description: Create a new SourceForge project.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '200':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /rest/p/{project}/has_access:
    get:
      operationId: checkProjectAccess
      summary: Check Project Access
      description: Check if the authenticated user has access to a project.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Access check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessResponse'
        '401':
          description: Unauthorized
  /rest/p/{project}/{wiki}:
    get:
      operationId: listWikiPages
      summary: List Wiki Pages
      description: List all wiki pages for a project.
      tags:
        - Wikis
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/WikiTool'
      responses:
        '200':
          description: List of wiki pages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WikiPagesResponse'
        '404':
          description: Project or wiki not found
  /rest/p/{project}/{wiki}/{title}:
    get:
      operationId: getWikiPage
      summary: Get Wiki Page
      description: Retrieve a specific wiki page by title.
      tags:
        - Wikis
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/WikiTool'
        - name: title
          in: path
          required: true
          description: Wiki page title
          schema:
            type: string
      responses:
        '200':
          description: Wiki page content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WikiPageResponse'
        '404':
          description: Wiki page not found
    post:
      operationId: createOrUpdateWikiPage
      summary: Create Or Update Wiki Page
      description: Create a new wiki page or update an existing one.
      tags:
        - Wikis
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/WikiTool'
        - name: title
          in: path
          required: true
          description: Wiki page title
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WikiPageRequest'
      responses:
        '200':
          description: Wiki page created or updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WikiPageResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /rest/p/{project}/{tracker}:
    get:
      operationId: listTickets
      summary: List Tickets
      description: List all tickets in the project tracker (paginated).
      tags:
        - Tracker
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/TrackerTool'
        - name: page
          in: query
          required: false
          description: Page number (default 0)
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          required: false
          description: Results per page (default 25)
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: List of tickets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketsResponse'
  /rest/p/{project}/{tracker}/new:
    post:
      operationId: createTicket
      summary: Create Ticket
      description: Create a new issue or ticket in the project tracker.
      tags:
        - Tracker
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/TrackerTool'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TicketRequest'
      responses:
        '200':
          description: Ticket created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /rest/p/{project}/{tracker}/{ticketNumber}:
    get:
      operationId: getTicket
      summary: Get Ticket
      description: Retrieve details for a specific ticket by number.
      tags:
        - Tracker
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/TrackerTool'
        - name: ticketNumber
          in: path
          required: true
          description: Ticket number
          schema:
            type: integer
      responses:
        '200':
          description: Ticket details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketResponse'
        '404':
          description: Ticket not found
  /rest/p/{project}/{tracker}/{ticketNumber}/save:
    post:
      operationId: updateTicket
      summary: Update Ticket
      description: Update an existing ticket's details.
      tags:
        - Tracker
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/TrackerTool'
        - name: ticketNumber
          in: path
          required: true
          description: Ticket number
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TicketRequest'
      responses:
        '200':
          description: Ticket updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /rest/p/{project}/{tracker}/search:
    get:
      operationId: searchTickets
      summary: Search Tickets
      description: Search tickets in the tracker with filtering.
      tags:
        - Tracker
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/TrackerTool'
        - name: q
          in: query
          required: false
          description: Search query string
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketsResponse'
  /rest/p/{project}/{discussion}:
    get:
      operationId: listForums
      summary: List Discussion Forums
      description: List all forums in the project discussion area.
      tags:
        - Discussion
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: discussion
          in: path
          required: true
          description: Discussion tool mount point
          schema:
            type: string
      responses:
        '200':
          description: List of forums
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForumsResponse'
  /rest/p/{project}/{discussion}/{forum}:
    get:
      operationId: listForumTopics
      summary: List Forum Topics
      description: Get topics in a specific discussion forum.
      tags:
        - Discussion
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: discussion
          in: path
          required: true
          schema:
            type: string
        - name: forum
          in: path
          required: true
          description: Forum identifier
          schema:
            type: string
      responses:
        '200':
          description: Forum topics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForumTopicsResponse'
  /rest/p/{project}/{discussion}/{forum}/thread/{thread}:
    get:
      operationId: listThreadPosts
      summary: List Thread Posts
      description: List all posts in a discussion thread.
      tags:
        - Discussion
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: discussion
          in: path
          required: true
          schema:
            type: string
        - name: forum
          in: path
          required: true
          schema:
            type: string
        - name: thread
          in: path
          required: true
          description: Thread identifier
          schema:
            type: string
      responses:
        '200':
          description: Thread posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadPostsResponse'
  /rest/p/{project}/{blog}:
    get:
      operationId: listBlogPosts
      summary: List Blog Posts
      description: List all blog posts for a project.
      tags:
        - Blog
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/BlogTool'
      responses:
        '200':
          description: List of blog posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogPostsResponse'
    post:
      operationId: createBlogPost
      summary: Create Blog Post
      description: Create a new blog post for the project.
      tags:
        - Blog
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/BlogTool'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BlogPostRequest'
      responses:
        '200':
          description: Blog post created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogPostResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /rest/p/{project}/{blog}/{year}/{month}/{title}:
    get:
      operationId: getBlogPost
      summary: Get Blog Post
      description: Retrieve a specific blog post.
      tags:
        - Blog
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/BlogTool'
        - name: year
          in: path
          required: true
          schema:
            type: integer
        - name: month
          in: path
          required: true
          schema:
            type: integer
        - name: title
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Blog post details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogPostResponse'
    post:
      operationId: updateBlogPost
      summary: Update Blog Post
      description: Update an existing blog post.
      tags:
        - Blog
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/BlogTool'
        - name: year
          in: path
          required: true
          schema:
            type: integer
        - name: month
          in: path
          required: true
          schema:
            type: integer
        - name: title
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BlogPostRequest'
      responses:
        '200':
          description: Blog post updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogPostResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /rest/p/{project}/admin/export:
    post:
      operationId: exportProject
      summary: Export Project
      description: Submit a project export job.
      tags:
        - Admin
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Export job submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '503':
          description: Service unavailable - export already running
  /rest/p/{project}/admin/export_status:
    get:
      operationId: getExportStatus
      summary: Get Export Status
      description: Check the status of a project export job.
      tags:
        - Admin
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Export job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportStatusResponse'
        '401':
          description: Unauthorized
  /rest/p/{project}/admin/install_tool:
    post:
      operationId: installTool
      summary: Install Tool
      description: Install a new tool into the project.
      tags:
        - Admin
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                tool:
                  type: string
                  description: Tool name to install
                mount_point:
                  type: string
                  description: URL mount point for the tool
                mount_label:
                  type: string
                  description: Display label for the tool
      responses:
        '200':
          description: Tool installed successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /rest/p/{project}/admin/{tool}/webhooks:
    get:
      operationId: listWebhooks
      summary: List Webhooks
      description: List all webhooks configured for a project tool.
      tags:
        - Admin
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: tool
          in: path
          required: true
          description: Tool mount point
          schema:
            type: string
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhooksResponse'
        '401':
          description: Unauthorized
  /rest/p/{project}/admin/{tool}/webhooks/{type}:
    post:
      operationId: createWebhook
      summary: Create Webhook
      description: Create a new webhook for a project tool (supports repo-push for Git, SVN, Mercurial).
      tags:
        - Admin
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: tool
          in: path
          required: true
          schema:
            type: string
        - name: type
          in: path
          required: true
          description: Webhook type (e.g., repo-push)
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
      responses:
        '200':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /rest/p/{project}/admin/{tool}/webhooks/{type}/{id}:
    post:
      operationId: updateWebhook
      summary: Update Webhook
      description: Update an existing webhook configuration.
      tags:
        - Admin
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: tool
          in: path
          required: true
          schema:
            type: string
        - name: type
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          description: Webhook identifier
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
      responses:
        '200':
          description: Webhook updated
        '400':
          description: Bad request
        '401':
          description: Unauthorized
    delete:
      operationId: deleteWebhook
      summary: Delete Webhook
      description: Delete a webhook configuration.
      tags:
        - Admin
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: tool
          in: path
          required: true
          schema:
            type: string
        - name: type
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Webhook deleted
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
  /rest/user:
    get:
      operationId: getCurrentUser
      summary: Get Current User
      description: Retrieve the authenticated user's profile.
      tags:
        - Users
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Unauthorized
  /rest/auth/tools/{tool_type}:
    get:
      operationId: listUserTools
      summary: List User Tools
      description: List all tools of the specified type accessible to the authenticated user.
      tags:
        - Users
      parameters:
        - name: tool_type
          in: path
          required: true
          description: Type of tool to list
          schema:
            type: string
      responses:
        '200':
          description: List of user tools
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolsResponse'
        '401':
          description: Unauthorized
  /rest/oauth2/token:
    post:
      operationId: getOAuthToken
      summary: Get OAuth2 Token
      description: Exchange authorization code for OAuth2 access token.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - code
              properties:
                grant_type:
                  type: string
                  enum:
                    - authorization_code
                code:
                  type: string
                redirect_uri:
                  type: string
                  format: uri
                client_id:
                  type: string
                code_verifier:
                  type: string
                  description: PKCE code verifier
      responses:
        '200':
          description: Access token response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth2 Bearer token
    OAuth1:
      type: apiKey
      in: header
      name: Authorization
      description: OAuth 1.0 authorization header
  parameters:
    ProjectId:
      name: project
      in: path
      required: true
      description: Project shortname/identifier
      schema:
        type: string
    WikiTool:
      name: wiki
      in: path
      required: true
      description: Wiki tool mount point (e.g., wiki, docs)
      schema:
        type: string
    TrackerTool:
      name: tracker
      in: path
      required: true
      description: Tracker tool mount point (e.g., tickets, bugs)
      schema:
        type: string
    BlogTool:
      name: blog
      in: path
      required: true
      description: Blog tool mount point (e.g., blog)
      schema:
        type: string
  schemas:
    Project:
      type: object
      properties:
        name:
          type: string
        shortname:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        created:
          type: string
          format: date-time
        tools:
          type: array
          items:
            type: object
    ProjectResponse:
      type: object
      properties:
        name:
          type: string
        shortname:
          type: string
        description:
          type: string
        url:
          type: string
    CreateProjectRequest:
      type: object
      required:
        - shortname
        - name
      properties:
        shortname:
          type: string
        name:
          type: string
        description:
          type: string
    AccessResponse:
      type: object
      properties:
        has_access:
          type: boolean
        permissions:
          type: array
          items:
            type: string
    WikiPage:
      type: object
      properties:
        title:
          type: string
        text:
          type: string
        labels:
          type: array
          items:
            type: string
        timestamp:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        author:
          type: string
    WikiPagesResponse:
      type: object
      properties:
        pages:
          type: array
          items:
            $ref: '#/components/schemas/WikiPage'
    WikiPageResponse:
      type: object
      properties:
        title:
          type: string
        text:
          type: string
        labels:
          type: array
          items:
            type: string
        timestamp:
          type: string
          format: date-time
    WikiPageRequest:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Wiki page content in Markdown or text format
        labels:
          type: string
          description: Comma-separated labels
    Ticket:
      type: object
      properties:
        ticket_num:
          type: integer
        summary:
          type: string
        description:
          type: string
        status:
          type: string
        assigned_to:
          type: string
        labels:
          type: array
          items:
            type: string
        created_date:
          type: string
          format: date-time
        mod_date:
          type: string
          format: date-time
        private:
          type: boolean
    TicketsResponse:
      type: object
      properties:
        tickets:
          type: array
          items:
            $ref: '#/components/schemas/Ticket'
        count:
          type: integer
        page:
          type: integer
        limit:
          type: integer
    TicketResponse:
      type: object
      properties:
        ticket:
          $ref: '#/components/schemas/Ticket'
    TicketRequest:
      type: object
      properties:
        ticket_form.summary:
          type: string
          description: Issue title
        ticket_form.description:
          type: string
          description: Detailed description
        ticket_form.status:
          type: string
        ticket_form.assigned_to:
          type: string
        ticket_form.labels:
          type: string
          description: Comma-separated tags
        ticket_form.private:
          type: boolean
    Forum:
      type: object
      properties:
        name:
          type: string
        shortname:
          type: string
        description:
          type: string
        num_topics:
          type: integer
    ForumsResponse:
      type: object
      properties:
        forums:
          type: array
          items:
            $ref: '#/components/schemas/Forum'
    ForumTopicsResponse:
      type: object
      properties:
        threads:
          type: array
          items:
            type: object
    ThreadPostsResponse:
      type: object
      properties:
        posts:
          type: array
          items:
            type: object
    BlogPost:
      type: object
      properties:
        title:
          type: string
        text:
          type: string
        labels:
          type: array
          items:
            type: string
        timestamp:
          type: string
          format: date-time
        author:
          type: string
    BlogPostsResponse:
      type: object
      properties:
        posts:
          type: array
          items:
            $ref: '#/components/schemas/BlogPost'
    BlogPostResponse:
      type: object
      properties:
        post:
          $ref: '#/components/schemas/BlogPost'
    BlogPostRequest:
      type: object
      required:
        - title
        - text
      properties:
        title:
          type: string
        text:
          type: string
        labels:
          type: string
    ExportJobResponse:
      type: object
      properties:
        status:
          type: string
        job_id:
          type: string
    ExportStatusResponse:
      type: object
      properties:
        status:
          type: string
        download_url:
          type: string
          format: uri
    Webhook:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        type:
          type: string
        active:
          type: boolean
        created:
          type: string
          format: date-time
    WebhooksResponse:
      type: object
      properties:
        webhooks:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
    WebhookResponse:
      type: object
      properties:
        webhook:
          $ref: '#/components/schemas/Webhook'
    WebhookRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Webhook callback URL
        secret:
          type: string
          description: Optional secret for webhook signature verification
    User:
      type: object
      properties:
        username:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        created:
          type: string
          format: date-time
    UserResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
    ToolsResponse:
      type: object
      properties:
        tools:
          type: array
          items:
            type: object
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        scope:
          type: string
security:
  - BearerAuth: []