SponsorUnited News API

openapi: 3.2.0
info:
  title: SponsorUnited News API
  version: v1
  description: News
tags:
- name: News
  description: News
paths:
  /api/news/active-articles:
    get:
      tags:
      - News
      summary: List active news articles
      description: Returns a paginated list of active curated news with optional filtering by tags, brands, properties, agencies, and markets
      operationId: e4fa099a4fa10fee9854622f2fd726f7
      parameters:
      - name: ActiveCuratedNewsRequest
        in: query
        schema:
          $ref: '#/components/schemas/ActiveCuratedNewsRequest'
      responses:
        '200':
          description: A paginated list of active curated news.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveCuratedNewsResource'
      security:
      - bearerAuth: []
  /api/news/all-articles:
    get:
      tags:
      - News
      summary: List all curated news articles
      description: Returns a paginated list of all curated news articles with optional filtering by company, agency, team, category, subcategory, league, news tag, reporter, and date range. Requires view news permission.
      operationId: getAllCuratedNews
      parameters:
      - name: perPage
        in: query
        description: Items per page
        schema:
          type: integer
      - name: company
        in: query
        description: Comma-separated company IDs
        schema:
          type: string
      - name: agency
        in: query
        description: Comma-separated agency IDs
        schema:
          type: string
      - name: team
        in: query
        description: Comma-separated team IDs
        schema:
          type: string
      - name: category
        in: query
        description: Comma-separated category IDs
        schema:
          type: string
      - name: subcategory
        in: query
        description: Comma-separated subcategory IDs
        schema:
          type: string
      - name: league
        in: query
        description: Comma-separated league IDs
        schema:
          type: string
      - name: newsTag
        in: query
        description: Comma-separated news tag IDs
        schema:
          type: string
      - name: reporter
        in: query
        description: Comma-separated reporter user IDs
        schema:
          type: string
      - name: publishedAfter
        in: query
        description: Filter articles published after this date
        schema:
          type: string
          format: date-time
      - name: publishedBefore
        in: query
        description: Filter articles published before this date
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Paginated list of curated news articles
          content:
            application/json:
              schema:
                properties:
                  current_page:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CuratedNews'
                  first_page_url:
                    type:
                    - string
                    - 'null'
                  from:
                    type:
                    - integer
                    - 'null'
                  last_page:
                    type: integer
                  last_page_url:
                    type: string
                  next_page_url:
                    type:
                    - string
                    - 'null'
                  path:
                    type: string
                  per_page:
                    type: integer
                  prev_page_url:
                    type:
                    - string
                    - 'null'
                  to:
                    type:
                    - integer
                    - 'null'
                  total:
                    type: integer
                type: object
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden — missing view news permission
      security:
      - bearerAuth: []
  /api/news/export/all-articles:
    get:
      tags:
      - News
      summary: Export curated news articles
      description: Downloads curated news articles as a file export with optional filtering by company, agency, team, category, subcategory, league, news tag, reporter, and date range.
      operationId: exportCuratedNews
      parameters:
      - name: company
        in: query
        description: Comma-separated company IDs
        schema:
          type: string
      - name: agency
        in: query
        description: Comma-separated agency IDs
        schema:
          type: string
      - name: team
        in: query
        description: Comma-separated team IDs
        schema:
          type: string
      - name: category
        in: query
        description: Comma-separated category IDs
        schema:
          type: string
      - name: subcategory
        in: query
        description: Comma-separated subcategory IDs
        schema:
          type: string
      - name: league
        in: query
        description: Comma-separated league IDs
        schema:
          type: string
      - name: newsTag
        in: query
        description: Comma-separated news tag IDs
        schema:
          type: string
      - name: reporter
        in: query
        description: Comma-separated reporter user IDs
        schema:
          type: string
      - name: publishedAfter
        in: query
        description: Filter articles published after this date
        schema:
          type: string
          format: date-time
      - name: publishedBefore
        in: query
        description: Filter articles published before this date
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: File download of exported news articles
        '401':
          description: Unauthenticated
      security:
      - bearerAuth: []
  /api/news/my-articles:
    get:
      tags:
      - News
      summary: List current user's curated news articles
      description: Returns a paginated list of curated news articles created by the authenticated user, with optional filtering by company, agency, team, category, subcategory, league, news tag, and date range.
      operationId: getOwnCuratedNews
      parameters:
      - name: perPage
        in: query
        description: Items per page
        schema:
          type: integer
      - name: company
        in: query
        description: Comma-separated company IDs
        schema:
          type: string
      - name: agency
        in: query
        description: Comma-separated agency IDs
        schema:
          type: string
      - name: team
        in: query
        description: Comma-separated team IDs
        schema:
          type: string
      - name: category
        in: query
        description: Comma-separated category IDs
        schema:
          type: string
      - name: subcategory
        in: query
        description: Comma-separated subcategory IDs
        schema:
          type: string
      - name: league
        in: query
        description: Comma-separated league IDs
        schema:
          type: string
      - name: newsTag
        in: query
        description: Comma-separated news tag IDs
        schema:
          type: string
      - name: publishedAfter
        in: query
        description: Filter articles published after this date
        schema:
          type: string
          format: date-time
      - name: publishedBefore
        in: query
        description: Filter articles published before this date
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Paginated list of the authenticated user's curated news articles
          content:
            application/json:
              schema:
                properties:
                  current_page:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CuratedNews'
                  first_page_url:
                    type:
                    - string
                    - 'null'
                  from:
                    type:
                    - integer
                    - 'null'
                  last_page:
                    type: integer
                  last_page_url:
                    type: string
                  next_page_url:
                    type:
                    - string
                    - 'null'
                  path:
                    type: string
                  per_page:
                    type: integer
                  prev_page_url:
                    type:
                    - string
                    - 'null'
                  to:
                    type:
                    - integer
                    - 'null'
                  total:
                    type: integer
                type: object
        '401':
          description: Unauthenticated
      security:
      - bearerAuth: []
  /api/news/submissions:
    get:
      tags:
      - News
      summary: List the global news submissions queue (all submitters)
      description: Returns submissions from every reporter by default. Pass reporter_id to scope to one submitter. Requires the view-news permission.
      operationId: 0fb580a718c731e722abe30c5b1ebcdf
      parameters:
      - name: page
        in: query
        schema:
          type: integer
      - name: per_page
        in: query
        schema:
          type: integer
      - name: status
        in: query
        description: Comma-separated list of statuses (e.g. pending,analysed,published,unpublished,declined). Passing 'declined' includes soft-deleted (recoverable) declined articles.
        schema:
          type: string
      - name: order_by
        in: query
        schema:
          type: string
          enum:
          - created_at
          - updated_at
          - published_at
          - title
          - status
          - url
      - name: order_direction
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: reporter_id
        in: query
        description: Optional. Scope the queue to a single submitter's submissions.
        schema:
          type: integer
      - name: from
        in: query
        description: Filter submissions created on or after this date (Y-m-d)
        schema:
          type: string
          format: date
      - name: to
        in: query
        description: Filter submissions created on or before this date (Y-m-d, inclusive)
        schema:
          type: string
          format: date
      - name: title
        in: query
        description: Filter by article title (case-insensitive substring). Combined with `url`, both must match (AND).
        schema:
          type: string
      - name: url
        in: query
        description: Filter by article URL (case-insensitive substring). Combined with `title`, both must match (AND).
        schema:
          type: string
      responses:
        '403':
          description: Forbidden — missing view news permission
        '200':
          description: Simple paginator JSON; `data` items are NewsSubmissionResource rows.
          content:
            application/json:
              schema:
                properties:
                  current_page:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsSubmissionResource'
                  first_page_url:
                    type:
                    - string
                    - 'null'
                  from:
                    type:
                    - integer
                    - 'null'
                  next_page_url:
                    type:
                    - string
                    - 'null'
                  path:
                    type: string
                  per_page:
                    type: integer
                  prev_page_url:
                    type:
                    - string
                    - 'null'
                  to:
                    type:
                    - integer
                    - 'null'
                type: object
      security:
      - bearerAuth: []
  /api/news/submissions/{id}:
    get:
      tags:
      - News
      summary: Get one news submission by id (global — any submitter)
      description: Returns any submission's detail so coordinators can open articles submitted by any user. Requires the view-news permission.
      operationId: 64e24c71ec4f499e6a74144a4c68dbeb
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Single submission row.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/NewsSubmissionResource'
                type: object
        '403':
          description: Forbidden — missing view news permission
        '404':
          description: Not found
      security:
      - bearerAuth: []
  /api/news/article:
    post:
      tags:
      - News
      summary: Create a curated news article
      description: Creates a new curated news article with associated companies, agencies, teams, and tags. Requires news administration permission.
      operationId: createCuratedNews
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - url
              - title
              - description
              properties:
                url:
                  description: 'Article URL. Must be unique among usable articles: a URL left behind by a failed article is accepted (that article is purged), while one belonging to a declined article is rejected until it is restored or deleted.'
                  type: string
                  format: url
                title:
                  description: Article title
                  type: string
                description:
                  description: Article description
                  type: string
                image:
                  description: Image URL for the article
                  type: string
                published_at:
                  description: Publication date (defaults to now)
                  type: string
                  format: date-time
                is_sponsorship:
                  type: boolean
                companies:
                  description: Array of company objects to associate
                  type: array
                  items:
                    properties:
                      id:
                        type: integer
                    type: object
                agencies:
                  description: Array of agency objects to associate
                  type: array
                  items:
                    properties:
                      id:
                        type: integer
                    type: object
                teams:
                  description: Array of team/property objects to associate
                  type: array
                  items:
                    properties:
                      id:
                        type: integer
                    type: object
                tags:
                  description: Array of news tag IDs
                  type: array
                  items:
                    type: integer
              type: object
      responses:
        '200':
          description: Article created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CuratedNews'
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden — missing news administration permission
        '422':
          description: Validation error
      security:
      - bearerAuth: []
  /api/news/article/{id}:
    put:
      tags:
      - News
      summary: Update a curated news article
      description: Updates an existing curated news article. If a new URL is provided and differs from the current one, the article metadata is re-fetched from the URL. Requires edit news permission.
      operationId: updateCuratedNews
      parameters:
      - name: id
        in: path
        description: Curated news article identifier
        required: true
        schema:
          type: integer
      requestBody:
        required: false
        content:
          application/json:
            schema:
              properties:
                url:
                  description: New article URL (must be unique if changed)
                  type: string
                  format: url
                title:
                  description: Article title
                  type: string
                description:
                  description: Article description
                  type: string
                image:
                  description: Image URL for the article
                  type: string
                published_at:
                  description: Publication date
                  type: string
                  format: date-time
                is_active:
                  description: Whether the article is active
                  type: boolean
                companies:
                  description: Array of company objects to sync
                  type: array
                  items:
                    properties:
                      id:
                        type: integer
                    type: object
                agencies:
                  description: Array of agency objects to sync
                  type: array
                  items:
                    properties:
                      id:
                        type: integer
                    type: object
                teams:
                  description: Array of team/property objects to sync
                  type: array
                  items:
                    properties:
                      id:
                        type: integer
                    type: object
                tags:
                  description: Array of news tag IDs to sync
                  type: array
                  items:
                    type: integer
              type: object
      responses:
        '200':
          description: Article updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CuratedNews'
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden — missing edit news permission
        '404':
          description: Article not found
        '422':
          description: Validation error (e.g. duplicate URL)
      security:
      - bearerAuth: []
    delete:
      tags:
      - News
      summary: Delete a curated news article
      description: Permanently deletes a curated news article. Requires edit news permission or reporter ownership.
      operationId: deleteCuratedNews
      parameters:
      - name: id
        in: path
        description: Curated news article identifier
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Article deleted successfully; response body is the article snapshot before deletion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CuratedNews'
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden — missing edit news permission and not article reporter
        '404':
          description: Article not found
      security:
      - bearerAuth: []
  /api/news/analyse:
    post:
      tags:
      - News
      summary: Bulk submit news article URLs for analysis
      description: Accepts an array of news article URLs, creates CuratedNews records in pending status, syncs brand/property/agency relationships, and dispatches each to the data-ingestion service for content extraction. Re-submitting a URL whose article previously failed returns it to pending and dispatches a fresh analysis; a URL already in the queue is reported as already_exists without dispatching anything.
      operationId: 3b3d00be711cb398df132e0a2134086e
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyseCuratedNewsRequest'
      responses:
        '201':
          description: URLs submitted for analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyseCuratedNewsResultsResource'
        '422':
          description: Validation error
        '403':
          description: Forbidden (missing news administration permission)
      security:
      - bearerAuth: []
  /api/news/article/{id}/publish:
    put:
      tags:
      - News
      summary: Publish a news article
      description: 'Publishes an article (was ''approve''): status becomes published, it is made active and appears on linked brand/property profiles. Allowed from analysed or unpublished. Only the reporter who submitted the article can publish it.'
      operationId: 23adff9f97c3a94e4aaffc552029477b
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Article published successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsSubmissionResource'
        '403':
          description: Forbidden — missing view-news permission
        '404':
          description: Article not found
        '422':
          description: Transition not allowed from the current status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResource'
      security:
      - bearerAuth: []
  /api/news/article/{id}/unpublish:
    put:
      tags:
      - News
      summary: Unpublish a news article
      description: Removes a published article from brand/property profiles and returns it to an editable draft (status unpublished), while keeping it in the queue and preserving its brand/property links so it can be republished. Allowed from published. Only the reporter who submitted the article can unpublish it.
      operationId: 12f229dfd29e8f99d1a3c0113f89df3c
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Article unpublished successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsSubmissionResource'
        '403':
          description: Forbidden — missing view-news permission
        '404':
          description: Article not found
        '422':
          description: Transition not allowed from the current status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResource'
      security:
      - bearerAuth: []
  /api/news/article/{id}/decline:
    put:
      tags:
      - News
      summary: Decline a news article
      description: 'Declines an article (was ''reject''): a recoverable soft-delete that removes it from the active queue. It remains in the Declined list and can be restored. Allowed from analysed, unpublished or published. Only the reporter who submitted the article can decline it.'
      operationId: 59fcc0bd30941e64cc924cb74494492b
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Article declined successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsSubmissionResource'
        '403':
          description: Forbidden — missing view-news permission
        '404':
          description: Article not found
        '422':
          description: Transition not allowed from the current status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResource'
      security:
      - bearerAuth: []
  /api/news/article/{id}/restore:
    put:
      tags:
      - News
      summary: Restore a declined news article
      description: Restores a declined (soft-deleted) article back to an editable, in-queue state (status analysed). Allowed from declined. Only the reporter who submitted the article can restore it.
      operationId: 70198b0ef22aa7c8bbfd9ea52ea615c8
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Article restored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsSubmissionResource'
        '403':
          description: Forbidden — missing view-news permission
        '404':
          description: Article not found
        '422':
          description: Transition not allowed from the current status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResource'
      security:
      - bearerAuth: []
  /api/news/article/preview:
    get:
      tags:
      - News
      summary: Preview news article
      description: Returns preview information for a news article URL including title, description, and image
      operationId: 9aace22b4f6a3d27111fb4cfbcdf7a20
      parameters:
      - name: url
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Preview news article.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CuratedNewsArticlePreviewResource'
      security:
      - bearerAuth: []
  /api/news/article/{id}/assets:
    get:
      tags:
      - News
      summary: List extracted assets for a curated news article
      operationId: listNewsAssets
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Asset rows ordered by match_status then confidence desc
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsAssetResource'
                type: object
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden — missing view news permission
        '404':
          description: Article not found
      security:
      - bearerAuth: []
    post:
      tags:
      - News
      summary: Manually add an asset to a curated news article (Quick Add)
      operationId: storeNewsAsset
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreNewsAssetRequest'
      responses:
        '201':
          description: Asset row created (source=manual, match_status=confirmed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsAssetResource'
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden — missing edit news permission
        '404':
          description: Article not found
        '422':
          description: Validation error
      security:
      - bearerAuth: []
  /api/news/article/{id}/assets/{assetId}:
    delete:
      tags:
      - News
      summary: Dismiss a news asset row (soft — sets match_status=dismissed)
      description: Soft-deletes via status change so subsequent re-imports won't resurrect the row (see NewsAssetImportService::PROTECTED_STATUSES).
      operationId: dismissNewsAsset
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: assetId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Asset dismissed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsAssetResource'
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden — missing edit news permission
        '404':
          description: Article or asset not found
      security:
      - bearerAuth: []
    patch:
      tags:
      - News
      summary: Update a news asset row (pick a different item_id, flip to confirmed)
      operationId: updateNewsAsset
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: assetId
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNewsAssetRequest'
      responses:
        '200':
          description: Asset row updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsAssetResource'
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden — missing edit news permission
        '404':
          description: Article or asset not found
        '422':
          description: Validation error
      security:
      - bearerAuth: []
  /api/news/submissions/{id}/contacts/add:
    post:
      tags:
      - News
      summary: Add the extracted contacts a reviewer selected
      description: Routes each selected row on whether its matched contact still resolves to a live platform contact. Matched rows are updated in place — the article quote is prepended to their notes and nothing else is touched. Every selected id is answered individually, so a partial failure stays visible.
      operationId: addNewsContacts
      parameters:
      - name: id
        in: path
        description: Curated news article id
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddNewsContactsRequest'
      responses:
        '200':
          description: Per-row outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsContactAddResultsResource'
        '403':
          description: Forbidden — missing edit news permission
        '404':
          description: Article not found
        '422':
          description: Empty selection, or an id that belongs to another article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResource'
      security:
      - bearerAuth: []
  /api/news/submissions/{id}/contacts/{newsContactId}/resolve:
    post:
      tags:
      - News
      summary: Create a contact from the LinkedIn profile a reviewer chose
      description: For a row the sourcing agent left as needs_review. The scrape is queued on the same paced batch a confident match uses, because it spends a real account's cookie, so the answer arrives on the article page rather than in this response.
      operationId: resolveNewsContact
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: newsContactId
        in: path
        required: true
        schema:
          type: integer

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sponsorunited/refs/heads/main/openapi/sponsorunited-news-api-openapi.yml